نود Figma در N8N

نود Figma در N8N

نود Figma در n8n برای ساخت اتوماسیون‌هایی استفاده می‌شود که به تغییرات، کامنت‌ها، حذف فایل‌ها یا انتشار نسخه‌های جدید در Figma واکنش نشان می‌دهند. با این نود می‌توان رویدادهای مهم طراحی را به ابزارهایی مثل Slack، Jira، Trello، Notion، Google Sheets، GitHub یا ایمیل متصل کرد و یک جریان کاری خودکار بین تیم طراحی، محصول و توسعه ساخت.

معرفی نود در N8N

Figma یکی از محبوب‌ترین ابزارهای طراحی رابط کاربری و همکاری تیمی است. در n8n، نود Figma معمولاً به‌صورت Trigger استفاده می‌شود؛ یعنی زمانی که اتفاقی در Figma رخ می‌دهد، ورکفلو به‌صورت خودکار اجرا می‌شود.

• نوع نود: Trigger / Integration
• کارکرد اصلی: دریافت رویدادهای Figma از طریق Webhook و شروع اجرای ورکفلو
• کاربرد اصلی: اتصال تغییرات طراحی به فرایندهای عملیاتی، اطلاع‌رسانی، ثبت گزارش، مدیریت تسک و هماهنگی بین تیم‌ها
• سطح مناسب: مبتدی و متوسط

این نود زمانی بسیار کاربردی است که تیم طراحی و تیم توسعه به‌صورت همزمان روی یک محصول کار می‌کنند و لازم است تغییرات فایل‌های Figma، کامنت‌ها یا نسخه‌های منتشرشده به شکل خودکار به سایر ابزارها منتقل شوند.

موارد استفاده

اطلاع‌رسانی تغییرات فایل طراحی در Slack

یکی از رایج‌ترین کاربردهای نود Figma این است که هر زمان یک فایل طراحی تغییر کرد، پیام خودکاری در Slack ارسال شود. برای مثال وقتی طراح رابط کاربری صفحه Checkout را به‌روزرسانی می‌کند، تیم فرانت‌اند بلافاصله از تغییر مطلع می‌شود.

• Figma Trigger: دریافت رویداد FILE_UPDATE
• IF: بررسی اینکه فایل مربوط به پروژه موردنظر است یا نه
• Slack: ارسال پیام به کانال تیم محصول یا توسعه

ثبت کامنت‌های Figma در Notion یا Google Sheets

اگر کامنت‌های زیادی در Figma ثبت می‌شود، می‌توان با کمک این نود همه کامنت‌ها را در یک دیتابیس Notion یا فایل Google Sheets ذخیره کرد. این کار برای گزارش‌گیری، پیگیری فیدبک‌ها و مدیریت تغییرات بسیار مفید است.

• Figma Trigger: دریافت رویداد FILE_COMMENT
• Set: آماده‌سازی داده‌ها مثل نام فایل، متن کامنت، نام کاربر و زمان ثبت
• Notion یا Google Sheets: ذخیره کامنت در جدول

ساخت تسک در Jira یا Trello بعد از انتشار نسخه جدید طراحی

زمانی که نسخه جدیدی از یک فایل Figma منتشر می‌شود، می‌توان به‌صورت خودکار یک کارت در Trello یا یک Issue در Jira ایجاد کرد تا تیم توسعه آن تغییرات را بررسی کند.

• Figma Trigger: دریافت رویداد FILE_VERSION_UPDATE
• Jira یا Trello: ایجاد تسک جدید برای بررسی نسخه طراحی
• Email یا Slack: اطلاع‌رسانی به مسئول مربوطه

کنترل کیفیت قبل از تحویل طراحی به توسعه

می‌توان بعد از هر تغییر در فایل Figma، یک ورکفلو اجرا کرد که اطلاعات فایل را از API فیگما دریافت کند و بر اساس قوانین داخلی تیم، وضعیت آماده بودن فایل را بررسی کند. برای مثال بررسی شود که فایل مربوط به پروژه درست است، نام‌گذاری صفحات استاندارد است یا کامنت‌های حل‌نشده وجود دارد.

• Figma Trigger: دریافت تغییرات فایل
• HTTP Request: دریافت اطلاعات تکمیلی از Figma API
• Code یا IF: بررسی قوانین داخلی تیم
• Slack یا Email: ارسال نتیجه بررسی

ثبت لاگ تغییرات طراحی در دیتابیس

برای تیم‌هایی که نیاز به تاریخچه تغییرات دارند، می‌توان هر رویداد Figma را در دیتابیس‌هایی مثل PostgreSQL، MySQL، Airtable یا Supabase ذخیره کرد.

• Figma Trigger: دریافت رویداد
• Set: ساختاردهی اطلاعات
• Database Node: ذخیره رویداد در جدول لاگ

پارامترها و تنظیمات

پارامترهای نود Figma در n8n ممکن است بسته به نسخه n8n و نوع پیاده‌سازی کمی متفاوت باشند، اما در حالت رایج، این نود برای دریافت Webhookهای Figma از تنظیمات زیر استفاده می‌کند.

Credentials یا اطلاعات اتصال

• نام پارامتر: Figma API Credential

  نوع داده: Credential / Secret

  توضیح کاربرد: برای اتصال n8n به حساب Figma استفاده می‌شود. معمولاً از Personal Access Token فیگما استفاده می‌شود.

  مثال عملی: توکنی که از بخش Account Settings در Figma ساخته می‌شود و در n8n به‌عنوان Credential ذخیره می‌گردد.

  نکته مهم: این توکن باید دسترسی لازم به تیم، پروژه یا فایل موردنظر را داشته باشد. اگر حساب Figma به فایل دسترسی نداشته باشد، n8n هم نمی‌تواند رویدادهای مربوط به آن را به‌درستی دریافت یا پردازش کند.

Team ID

• نام پارامتر: Team ID

  نوع داده: String

  توضیح کاربرد: شناسه تیم Figma که می‌خواهید رویدادهای آن را مانیتور کنید. این مقدار مشخص می‌کند Webhook برای کدام تیم فعال شود.

  مثال عملی: اگر آدرس تیم در Figma به شکل https://www.figma.com/files/team/123456789012345678 باشد، مقدار Team ID برابر 123456789012345678 است.

  نکته مهم: Team ID با File Key متفاوت است. File Key شناسه فایل است، اما Team ID شناسه تیمی است که فایل‌ها و پروژه‌ها زیرمجموعه آن قرار دارند.

Event یا Trigger On

• نام پارامتر: Event / Trigger On

  نوع داده: Options یا Multi Options

  توضیح کاربرد: مشخص می‌کند ورکفلو با چه نوع رویدادی از Figma اجرا شود.

  مثال عملی: انتخاب FILE_UPDATE برای اجرای ورکفلو هنگام تغییر فایل طراحی.

  گزینه‌های رایج:

  • FILE_UPDATE: زمانی که فایل Figma تغییر می‌کند.
  • FILE_VERSION_UPDATE: زمانی که نسخه جدیدی از فایل منتشر یا ثبت می‌شود.
  • FILE_DELETE: زمانی که یک فایل حذف می‌شود.
  • FILE_COMMENT: زمانی که روی فایل کامنت جدیدی ثبت می‌شود یا رویداد مرتبط با کامنت رخ می‌دهد.
  • LIBRARY_PUBLISH: زمانی که کتابخانه یا Library منتشر می‌شود، در صورتی که توسط نسخه n8n و API فیگما پشتیبانی شود.

  نکته مهم: همه رویدادها ممکن است در همه نسخه‌های n8n یا همه پلن‌های Figma در دسترس نباشند. همچنین ساختار خروجی هر Event می‌تواند متفاوت باشد.

Webhook URL

• نام پارامتر: Webhook URL

  نوع داده: URL

  توضیح کاربرد: آدرسی است که Figma هنگام رخ دادن رویداد، داده‌ها را به آن ارسال می‌کند. در n8n این آدرس معمولاً به‌صورت خودکار توسط نود ساخته می‌شود.

  مثال عملی: https://n8n.example.com/webhook/figma-trigger

  نکته مهم: برای استفاده واقعی، n8n باید از اینترنت قابل دسترسی باشد و آدرس HTTPS معتبر داشته باشد. در حالت لوکال، استفاده از Tunnel یا n8n Cloud می‌تواند لازم باشد.

Test URL و Production URL

• نام پارامتر: Test URL / Production URL

  نوع داده: URL

  توضیح کاربرد: در n8n، نودهای Trigger معمولاً دو حالت دارند؛ حالت تست برای دریافت نمونه داده هنگام طراحی ورکفلو و حالت Production برای اجرای واقعی بعد از فعال‌سازی ورکفلو.

  مثال عملی: هنگام تست، روی Execute Workflow کلیک می‌شود و n8n منتظر دریافت اولین رویداد Figma می‌ماند. بعد از فعال شدن ورکفلو، آدرس Production استفاده می‌شود.

  نکته مهم: اگر ورکفلو فعال نباشد، رویدادهای واقعی ممکن است پردازش نشوند.

Passcode یا Secret

• نام پارامتر: Passcode / Secret

  نوع داده: String / Secret

  توضیح کاربرد: برای اعتبارسنجی درخواست‌هایی که از سمت Figma به n8n ارسال می‌شوند استفاده می‌شود. در بسیاری از پیاده‌سازی‌ها این مقدار توسط n8n مدیریت می‌شود.

  مثال عملی: یک مقدار تصادفی مثل figma-webhook-secret-2025 برای اطمینان از اینکه درخواست واقعاً از Webhook معتبر آمده است.

  نکته مهم: اگر این مقدار در تنظیمات قابل مشاهده بود، آن را عمومی نکنید و در پیام‌ها یا لاگ‌های قابل دسترس ذخیره نکنید.

تنظیمات عمومی نود در n8n

• نام پارامتر: Retry On Fail

  نوع داده: Boolean

  توضیح کاربرد: در برخی نودهای بعدی ورکفلو می‌توان فعال کرد تا در صورت خطای موقت، عملیات دوباره اجرا شود.

  مثال عملی: اگر ارسال پیام به Slack به دلیل خطای شبکه ناموفق بود، n8n دوباره تلاش کند.

• نام پارامتر: Continue On Fail

  نوع داده: Boolean

  توضیح کاربرد: باعث می‌شود اگر یک مرحله از ورکفلو خطا داد، کل جریان متوقف نشود.

  مثال عملی: اگر ثبت داده در Google Sheets ناموفق بود، همچنان پیام خطا در Slack ارسال شود.

• نام پارامتر: Notes

  نوع داده: Text

  توضیح کاربرد: برای مستندسازی داخل خود ورکفلو استفاده می‌شود.

  مثال عملی: نوشتن توضیحی مثل «این نود تغییرات تیم طراحی محصول را از Figma دریافت می‌کند».

ورودی‌ها و خروجی‌ها

ورودی نود Figma

از آنجا که Figma در n8n معمولاً یک Trigger Node است، ورودی مستقیمی از نود قبلی دریافت نمی‌کند. این نود شروع‌کننده ورکفلو است و زمانی اجرا می‌شود که Figma یک رویداد را از طریق Webhook ارسال کند.

• Input مستقیم: ندارد
• منبع داده: رویداد ارسال‌شده از سمت Figma
• زمان اجرا: هنگام رخ دادن Event انتخاب‌شده مانند تغییر فایل، ثبت کامنت یا انتشار نسخه

خروجی نود Figma

خروجی نود شامل اطلاعات رویدادی است که در Figma رخ داده است. ساختار دقیق خروجی به نوع Event بستگی دارد. برای مثال خروجی FILE_UPDATE با FILE_COMMENT یکسان نیست.

نمونه خروجی رایج برای رویداد به‌روزرسانی فایل:

{  "event_type": "FILE_UPDATE",  "file_key": "AbCdEf123456",  "file_name": "Mobile App Design",  "team_id": "123456789012345678",  "timestamp": "2025-01-20T10:30:00Z",  "triggered_by": {    "id": "99887766",    "handle": "Sara Designer",    "img_url": "https://www.figma.com/profile-image.png"  }}

نمونه خروجی رایج برای رویداد کامنت:

{  "event_type": "FILE_COMMENT",  "file_key": "AbCdEf123456",  "file_name": "Mobile App Design",  "timestamp": "2025-01-20T11:05:00Z",  "triggered_by": {    "id": "11223344",    "handle": "Product Manager"  },  "comment": {    "id": "comment_123",    "message": "لطفاً فاصله دکمه‌ها در نسخه موبایل بررسی شود.",    "client_meta": {      "node_id": "45:120"    }  }}

فیلدهای مهم خروجی

• event_type: نوع رویداد رخ‌داده در Figma، مثل FILE_UPDATE یا FILE_COMMENT.
• file_key: شناسه فایل Figma. این مقدار برای دریافت اطلاعات تکمیلی فایل از Figma API بسیار مهم است.
• file_name: نام فایل طراحی.
• team_id: شناسه تیم مرتبط با رویداد.
• timestamp: زمان وقوع رویداد.
• triggered_by: اطلاعات کاربری که باعث ایجاد رویداد شده است.
• comment: اطلاعات کامنت، فقط در رویدادهای مرتبط با کامنت وجود دارد.

استفاده از خروجی در نودهای بعدی

در n8n می‌توان از Expression برای استفاده از داده‌های خروجی استفاده کرد. چند نمونه رایج:

• نام فایل: {{$json.file_name}}
• شناسه فایل: {{$json.file_key}}
• نوع رویداد: {{$json.event_type}}
• نام کاربر ایجادکننده رویداد: {{$json.triggered_by.handle}}
• متن کامنت: {{$json.comment.message}}

نکات پیشرفته و ترفندها

فیلتر کردن رویدادها بر اساس فایل خاص

اگر Webhook در سطح تیم فعال باشد، ممکن است رویدادهای زیادی از فایل‌های مختلف دریافت شود. برای محدود کردن پردازش به یک فایل خاص، از نود IF استفاده کنید و مقدار file_key را بررسی کنید.

• شرط: {{$json.file_key}} برابر با AbCdEf123456 باشد
• مسیر True: ادامه پردازش رویداد
• مسیر False: پایان جریان یا ثبت لاگ ساده

دریافت اطلاعات کامل فایل با HTTP Request

خروجی Figma Trigger معمولاً فقط اطلاعات رویداد را شامل می‌شود. اگر به جزئیات کامل فایل، صفحات، کامپوننت‌ها یا نودهای طراحی نیاز دارید، می‌توانید بعد از Figma Trigger از نود HTTP Request استفاده کنید و به Figma API درخواست بفرستید.

• Method: GET
• URL: https://api.figma.com/v1/files/{{$json.file_key}}
• Header: X-Figma-Token: مقدار توکن Figma

این روش برای ساخت گزارش‌های پیشرفته، بررسی ساختار فایل یا استخراج اطلاعات طراحی بسیار کاربردی است.

جلوگیری از اجرای بیش‌ازحد ورکفلو

در فایل‌های فعال Figma ممکن است تغییرات زیادی در مدت کوتاه رخ دهد. برای جلوگیری از اجرای زیاد ورکفلو می‌توان از تکنیک Debounce استفاده کرد.

• استفاده از Wait برای تأخیر چند دقیقه‌ای
• ذخیره آخرین زمان پردازش در Data Store
• نادیده گرفتن رویدادهای تکراری در بازه زمانی کوتاه
• ترکیب event_type، file_key و timestamp برای ساخت شناسه یکتا

ساخت پیام‌های خوانا برای Slack یا Email

داده خام Webhook برای اعضای تیم همیشه خوانا نیست. بهتر است قبل از ارسال پیام، با نود Set یا Code متن پیام را قالب‌بندی کنید.

نمونه متن پیام:

فایل طراحی به‌روزرسانی شدنام فایل: {{$json.file_name}}نوع رویداد: {{$json.event_type}}توسط: {{$json.triggered_by.handle}}زمان: {{$json.timestamp}}

ترکیب با Jira برای مدیریت فرایند طراحی تا توسعه

یک الگوی حرفه‌ای این است که بعد از انتشار نسخه جدید طراحی، به‌صورت خودکار یک Issue در Jira ساخته شود و لینک فایل Figma داخل آن قرار بگیرد.

• Figma Trigger: دریافت FILE_VERSION_UPDATE
• Set: ساخت عنوان و توضیحات Issue
• Jira: ایجاد Issue در پروژه موردنظر
• Slack: ارسال لینک Issue به کانال تیم

ثبت رویدادها برای تحلیل عملکرد تیم طراحی

با ذخیره رویدادهای Figma در دیتابیس، می‌توان گزارش‌هایی مثل تعداد تغییرات فایل‌ها، تعداد کامنت‌ها، فعالیت کاربران و زمان‌های پرتکرار تغییرات طراحی ایجاد کرد.

• Figma Trigger: دریافت رویدادها
• PostgreSQL یا MySQL: ذخیره داده
• Metabase یا Looker Studio: ساخت داشبورد تحلیلی

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

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

• عدم ویرایش مستقیم فایل طراحی: نود Figma Trigger برای دریافت رویداد است، نه ویرایش مستقیم فایل‌های Figma.
• نیاز به دسترسی حساب: توکن Figma فقط به فایل‌ها و تیم‌هایی دسترسی دارد که حساب کاربری مربوطه مجاز به مشاهده یا مدیریت آن‌ها باشد.
• وابستگی به Webhook: اگر n8n از اینترنت قابل دسترسی نباشد، Figma نمی‌تواند رویدادها را به آن ارسال کند.
• تفاوت ساختار خروجی رویدادها: همه Eventها فیلدهای یکسان ندارند. برای مثال comment فقط در رویدادهای کامنت وجود دارد.
• محدودیت نرخ API: هنگام استفاده از HTTP Request برای دریافت اطلاعات تکمیلی، باید محدودیت‌های Rate Limit فیگما رعایت شود.
• وابستگی به نسخه n8n: برخی Eventها یا تنظیمات ممکن است فقط در نسخه‌های جدیدتر n8n پشتیبانی شوند.

خطای Invalid Credentials

علت: توکن Figma اشتباه، منقضی یا فاقد دسترسی لازم است.

راه‌حل: یک Personal Access Token جدید در Figma بسازید، آن را در Credentials n8n ذخیره کنید و مطمئن شوید حساب مربوطه به تیم یا فایل موردنظر دسترسی دارد.

خطای Webhook Not Reachable

علت: آدرس n8n از سمت اینترنت قابل دسترسی نیست یا HTTPS معتبر ندارد.

راه‌حل: از n8n Cloud، دامنه عمومی با SSL معتبر یا Tunnel مناسب برای محیط تست استفاده کنید. در محیط Production بهتر است n8n روی دامنه پایدار و امن اجرا شود.

دریافت نکردن رویدادها بعد از فعال‌سازی ورکفلو

علت: ورکفلو فعال نیست، Team ID اشتباه وارد شده، Event درست انتخاب نشده یا Webhook در Figma ثبت نشده است.

راه‌حل: وضعیت Active بودن ورکفلو را بررسی کنید، Team ID را از URL رسمی تیم کپی کنید، نوع Event را کنترل کنید و در صورت نیاز Credential را دوباره متصل کنید.

خطای Permission Denied یا 403

علت: توکن Figma به تیم، فایل یا پروژه موردنظر دسترسی ندارد.

راه‌حل: دسترسی حساب کاربری Figma را بررسی کنید. اگر فایل در تیم دیگری قرار دارد، باید حساب متصل‌شده به n8n به آن تیم دسترسی داشته باشد.

پردازش چندباره یک رویداد

علت: ارسال مجدد Webhook، اجرای همزمان چند Workflow یا نبود کنترل یکتایی در داده‌ها.

راه‌حل: از Data Store، دیتابیس یا Redis برای ذخیره شناسه رویدادهای پردازش‌شده استفاده کنید و قبل از ادامه جریان بررسی کنید که همان رویداد قبلاً پردازش نشده باشد.

خطا در خواندن فیلدهای خروجی

علت: استفاده از فیلدی که در نوع Event فعلی وجود ندارد. برای مثال استفاده از {{$json.comment.message}} در رویداد FILE_UPDATE باعث خروجی خالی یا خطا در برخی نودها می‌شود.

راه‌حل: قبل از استفاده از فیلدهای اختیاری، با IF یا Expression بررسی کنید که فیلد وجود دارد.

ایده ها

• سیستم اعلان تغییرات طراحی: هر بار که فایل مهمی در Figma تغییر کرد، پیام خلاصه‌شده‌ای در Slack یا Microsoft Teams ارسال شود.
• داشبورد فعالیت تیم طراحی: همه رویدادهای Figma در دیتابیس ذخیره شوند و داشبوردی برای تحلیل تعداد تغییرات، کامنت‌ها و نسخه‌ها ساخته شود.
• تبدیل کامنت‌های Figma به تسک: کامنت‌هایی که شامل کلمات خاص مثل bug، fix یا urgent هستند به‌صورت خودکار به Jira یا Trello منتقل شوند.
• کنترل آماده بودن طراحی برای توسعه: بعد از انتشار نسخه جدید، ورکفلو بررسی کند که فایل لینک، توضیح، نسخه و نام‌گذاری استاندارد داشته باشد.
• ثبت تاریخچه نسخه‌های طراحی: هنگام FILE_VERSION_UPDATE اطلاعات نسخه در Notion، Airtable یا Google Sheets ذخیره شود تا تاریخچه تحویل طراحی قابل پیگیری باشد.

منابع و مستندات اصلی

• مستندات رسمی Figma Trigger در n8n
• مستندات Credentials مربوط به Figma در n8n
• مستندات نود HTTP Request در n8n
• مستندات رسمی Figma API
• مستندات Webhooks در Figma API
• انجمن رسمی n8n برای پرسش‌ها و نمونه ورکفلوها