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

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

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

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

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

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

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

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

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

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

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

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

1. به Assistants بروید.
2. برگه Workflow assistants را باز کنید.
3. در کارت بالا روی New workflow کلیک کنید و n8n workflow را انتخاب کنید.
4. نام گردش‌کار و آدرس تولیدی n8n را وارد کنید.
5. Header authentication را با یک نام هدر و مقدار مخفی هدر تنظیم کنید.
6. در بخش Callbacks from n8n فقط آن بخش‌هایی را تیک بزنید که واقعاً در این گردش‌کار n8n ساخته شده‌اند: پیشرفت، تأیید و/یا پایان گردش‌کار.
7. در صورت نیاز، فیلدهایی را اضافه کنید که باید در درخواست POST ارسال شوند.
8. گردش‌کار را ذخیره کنید.

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

فیلدها

• فیلدها اختیاری هستند.
• هر فیلد یک نام فیلد و یک نوع دارد.
• نوع‌های پشتیبانی‌شده عبارت‌اند از متن کوتاه، متن بلند، عدد، بله/خیر، تاریخ، یک انتخاب و چند انتخاب.
• برای یک انتخاب و چند انتخاب، گزینه‌های موجود را اضافه می‌کنید. یک انتخاب به‌صورت یک فهرست انتخاب فشرده نمایش داده می‌شود؛ چند انتخاب چک‌باکس‌ها را نشان می‌دهد. مقدار یا مقادیر انتخاب‌شده در بدنه JSON ارسال می‌شوند.
• فیلدهای اجباری باید قبل از شروع گردش‌کار تکمیل شده باشند.
• نام فیلد به کلید (key) در بدنه JSON تبدیل می‌شود که به n8n ارسال می‌گردد.

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

1. در n8n یک گردش‌کار جدید بسازید.
2. به‌عنوان اولین node یک Webhook اضافه کنید.
3. نام این node را دقیقاً Start workflow بگذارید. نمونه‌عبارت‌های زیر از این نام استفاده می‌کنند.
4. HTTP Method را روی POST بگذارید.
5. Authentication: Header Auth را انتخاب کنید و همان نام هدر و مقدار مخفی را که در AI-Public استفاده شده به کار ببرید.
6. Respond یا Response Mode را روی Immediately بگذارید.
7. Production URL را به فیلد n8n production url در AI-Public کپی کنید. از test-url با /webhook-test/ استفاده نکنید.
8. گردش‌کار را فعال کنید.

داده‌های دریافت‌شده زیر body قرار دارند؛ داده‌های فنی یکپارچه‌سازی زیر body.integration هستند. آن‌ها را در یک Edit Fields، Set یا Code node حذف نکنید.

نمونه‌ای از بدنه JSON

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

{
  "prompt": "یک خلاصه کوتاه از درخواست بنویس.",
  "klantnaam": "سازمان نمونه",
  "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": "توکن موقت برای این اجرا"
  }
}

توکن callback فقط مربوط به یک اجراست. آن را در لاگ‌ها، پیکربندی ثابت یا سیستم‌های دیگر ذخیره نکنید.

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

AI-Public فقط می‌تواند چیزی را نشان دهد که n8n بازمی‌گرداند. از این callbackها فقط زمانی استفاده کنید که در ثبت، گزارش پیشرفت میانی و/یا گزارش پایان گردش‌کار را فعال کرده باشید.

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

• برای هر رویداد در یک اجرای واحد، یک eventId یکتا استفاده کنید.
• از یک step.label واضح و فارسی استفاده کنید؛ این متن در برنامه نمایش داده می‌شود.
• اگر گزارش پایان گردش‌کار را فعال کرده‌اید، در پایان همیشه type: "completed"، type: "failed" یا type: "rejected" بفرستید.
• در completed می‌توانید یک شیء output شامل نتیجه اضافه کنید.
• در failed یک پیام خطای قابل‌فهم بفرستید. در این صورت اجرا در برنامه نیز متوقف می‌شود.

اختیاری: درخواست تأیید در برنامه

وقتی گردش‌کار فقط بعد از یک انتخاب باید ادامه پیدا کند، از یک n8n Wait node با On Webhook Call استفاده کنید. قبل از Wait node یک callback با type: "approval_required" بفرستید:

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

کاربر گزینه‌ها را در پنجره اجرا می‌بیند. پس از انتخاب، Wait node از جمله decision را دریافت می‌کند. سپس مثلاً از یک Switch node برای تعیین ادامه درست استفاده کنید.

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

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

آدرس callback تولیدی برای AI-Public این است:

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

این URL را به‌صورت متن ثابت در هر callback node قرار ندهید. در فیلد URLِ node درخواست HTTP، Expression را انتخاب کنید و از این استفاده کنید:

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

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

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

مدیریت خطاها

خطاهای مورد انتظار را با یک callback از نوع failed برگردانید. برای خطاهای غیرمنتظره nodeها، علاوه بر آن یک Error Workflow مرکزی بسازید:

1. یک گردش‌کار جدید با یک node Error Trigger بسازید.

2. سپس یک node 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 می‌تواند یک خطای غیرمنتظره را به اجرای درست متصل کند.

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

• فقط triggerهای webhook پشتیبانی می‌شوند.
• فقط آدرس‌های webhook تولیدی پشتیبانی می‌شوند.
• آدرس‌های test-webhook با /webhook-test/ رد می‌شوند.
• فقط POST پشتیبانی می‌شود.
• فقط generic header authentication پشتیبانی می‌شود.
• مقدار هدر در برنامه به‌عنوان محرمانه در نظر گرفته می‌شود.
• callbacktokenها و resume-urlها فقط در سمت سرور پردازش می‌شوند و مستقیماً برای کاربران در دسترس نیستند.
• tenant به‌صورت سمت‌سرور و بر اساس کاربر واردشده تعیین می‌شود، نه از روی مقداری که مرورگر ارسال می‌کند.

رفع مشکل

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