نود XML در N8N

نود XML در n8n برای تبدیل داده‌ها بین XML و JSON استفاده می‌شود؛ یعنی وقتی از یک API، فایل، وب‌سرویس یا سیستم‌های قدیمی (Legacy) خروجی XML می‌گیرید یا باید به یک سرویس XML ارسال کنید، این نود نقش پل ارتباطی را بازی می‌کند. نتیجه این است که می‌توانید داده‌های XML را مثل بقیه داده‌های n8n (که عموماً JSON هستند) پردازش، فیلتر، ترکیب و ذخیره کنید.

معرفی نود در N8N

این نود چه کاری انجام می‌دهد؟

نود XML معمولاً دو کار اصلی انجام می‌دهد:

تبدیل XML به JSON برای پردازش راحت‌تر در n8n
تبدیل JSON به XML برای ارسال به سرویس‌هایی که XML می‌پذیرند

دسته‌بندی نود

Function / Data Transformation: این نود یک نود تبدیلی است و بیشتر برای تبدیل ساختار داده به‌کار می‌رود.

اهمیت در ورکفلوها

بخش زیادی از سرویس‌های مدرن JSON می‌دهند، اما هنوز در بسیاری از سازمان‌ها و یکپارچه‌سازی‌ها، XML رایج است (SOAP، فیدهای قدیمی، فایل‌های تبادلی). با XML Node می‌توانید:

ورودی XML را به داده قابل پردازش تبدیل کنید (برای IF، Set، Merge، Code و…)
خروجی JSON را به XML استاندارد تبدیل کنید تا برای سیستم مقصد قابل قبول باشد
فرآیندهای ETL را ساده‌تر کنید (Extract/Transform/Load)

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

۱) خواندن پاسخ XML از یک API و استخراج فیلدها

سناریو: با HTTP Request یک وب‌سرویس خروجی XML می‌دهد. شما نیاز دارید برخی فیلدها را استخراج و در Google Sheets ذخیره کنید.

HTTP Request (دریافت XML)
XML (XML → JSON)
Set (انتخاب و تمیزکردن فیلدها)
Google Sheets (ثبت رکورد)

۲) تولید XML برای ارسال به سیستم‌های قدیمی

سناریو: سیستم مقصد فقط XML می‌پذیرد (مثلاً یک ERP قدیمی). شما داده را از Airtable/DB می‌گیرید و باید XML بسازید.

Postgres / Airtable (دریافت JSON)
Set یا Code (آماده‌سازی ساختار)
XML (JSON → XML)
HTTP Request (ارسال XML با Content-Type مناسب)

۳) تبدیل فایل XML به ساختار قابل گزارش‌گیری

سناریو: فایل XML از طریق Email/FTP دریافت می‌شود و باید تبدیل به JSON و سپس تبدیل به CSV شود.

Email Trigger / FTP (دریافت فایل)
Read Binary File یا Move Binary Data (تبدیل به متن)
XML (XML → JSON)
Spreadsheet File (تولید CSV/Excel)

۴) پردازش فیدهای XML مثل RSS/Atom

سناریو: یک RSS را می‌خوانید، آیتم‌های جدید را جدا می‌کنید و به تلگرام/اسلک می‌فرستید.

HTTP Request (دریافت RSS)
XML (XML → JSON)
Item Lists / Code (استخراج آیتم‌ها)
Slack / Telegram (ارسال)

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

تنظیمات ممکن است بسته به نسخه n8n کمی تفاوت نام داشته باشند، اما مفهوم فیلدها ثابت است: انتخاب عملیات، تعیین فیلد ورودی و تنظیم رفتار تبدیل.

۱) Operation (عملیات)

نام پارامتر: Operation
نوع داده: گزینه‌ای (Option)
توضیح: مشخص می‌کند تبدیل در چه جهتی انجام شود.
مثال عملی:
- XML to JSON: وقتی پاسخ API به صورت XML است.
- JSON to XML: وقتی باید به سرویس مقصد XML ارسال کنید.

۲) Property Name / Input Field (نام فیلد ورودی)

نام پارامتر: Property Name (یا مشابه)
نوع داده: رشته (String)
توضیح: تعیین می‌کند XML یا JSON از کدام پراپرتی در آیتم ورودی خوانده شود.
مثال عملی:
- اگر HTTP Request خروجی را در body می‌گذارد، مقدار را body قرار دهید.
- اگر شما قبلاً با Set یک فیلد به نام xml ساخته‌اید، مقدار را xml بگذارید.

۳) Options (گزینه‌های تبدیل)

این بخش برای کنترل جزئیات تبدیل است. در برخی نسخه‌ها گزینه‌ها متفاوت‌اند، اما رایج‌ترین‌ها شامل موارد زیر است:

Ignore Attributes / Parse Attributes
- نوع داده: بولی (Boolean)
- توضیح: تعیین می‌کند attributeهای XML مثل <item id="10"> در JSON نگهداری شوند یا نادیده گرفته شوند.
- مثال: اگر برای شما id مهم است، این گزینه را طوری تنظیم کنید که attributeها حفظ شوند.
Explicit Array / Always Create Arrays
- نوع داده: بولی (Boolean)
- توضیح: بعضی XMLها وقتی یک عنصر فقط یک‌بار تکرار شده باشد، در JSON به صورت آبجکت می‌آید نه آرایه. فعال کردن این گزینه باعث می‌شود خروجی پایدارتر شود.
- مثال: برای فیدهایی که گاهی ۱ آیتم و گاهی چند آیتم دارند، این گزینه از بهم‌ریختگی ورکفلو جلوگیری می‌کند.
Trim / Normalize
- نوع داده: بولی (Boolean)
- توضیح: فاصله‌های اضافی یا فرمت متن را یکدست می‌کند.
- مثال: وقتی متن‌ها شامل newline یا space اضافی هستند و قرار است در DB ذخیره شوند.
Root Name (برای JSON → XML)
- نوع داده: رشته (String)
- توضیح: نام تگ ریشه XML خروجی را مشخص می‌کند.
- مثال: Request یا Envelope بسته به نیاز سرویس مقصد.
CDATA (برای JSON → XML)
- نوع داده: بولی (Boolean) یا تنظیمات متنی
- توضیح: برای متن‌هایی که ممکن است شامل کاراکترهای خاص باشند (مثل & یا <) می‌توانید از CDATA استفاده کنید.
- مثال: ارسال توضیحات محصول یا HTML به سرویس مقصد.

نکات مهم هنگام پیکربندی

ورودی باید متن XML معتبر باشد؛ اگر خروجی شما باینری است، ابتدا آن را به متن تبدیل کنید.
Encoding می‌تواند مشکل‌ساز شود؛ اگر کاراکترهای فارسی به‌هم می‌ریزند، مطمئن شوید متن با UTF-8 منتقل می‌شود.
اگر XML شما namespace دارد (مثل <ns:Tag>) ممکن است مسیرهای دسترسی در JSON پیچیده‌تر شوند؛ خروجی را در Execution Data بررسی کنید.

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

ورودی (Input)

هر آیتم ورودی باید یک فیلد متنی (String) داشته باشد که XML یا JSON در آن قرار گرفته است (بسته به Operation).

نمونه ورودی برای XML → JSON:

{  "body": "<note><to>Ali</to><from>Sara</from><message>Hello</message></note>"}

خروجی (Output)

خروجی به صورت JSON استاندارد n8n برمی‌گردد. برای مثال، تبدیل نمونه بالا معمولاً چیزی شبیه این می‌دهد:

{  "note": {    "to": "Ali",    "from": "Sara",    "message": "Hello"  }}

نمونه ورودی برای JSON → XML

{  "payload": {    "note": {      "to": "Ali",      "from": "Sara",      "message": "Hello"    }  }}

اگر Property Name را payload بگذارید، خروجی XML می‌تواند مشابه زیر باشد (بسته به تنظیم Root و Options):

<note>  <to>Ali</to>  <from>Sara</from>  <message>Hello</message></note>

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

۱) پایدار کردن ساختار با آرایه‌ها

در XMLهایی که یک تگ ممکن است یک‌بار یا چندبار تکرار شود، خروجی JSON ممکن است گاهی آبجکت و گاهی آرایه شود. برای جلوگیری از خطا در مراحل بعدی (مثل Item Lists یا Code)، گزینه‌ای مثل Always Create Arrays را فعال کنید یا با Code خروجی را نرمال کنید.

۲) ساخت XML مطابق نیاز سرویس مقصد

بسیاری از سرویس‌ها به ساختار دقیق حساس‌اند (نام تگ ریشه، ترتیب تگ‌ها، attributeها). اگر نود XML خروجی کاملاً مطابق نبود:

قبل از XML Node، با Set/Code ساختار JSON را دقیقاً مطابق تگ‌های موردنیاز بسازید.
برای کنترل بیشتر روی خروجی، در مرحله آخر از Code برای تولید رشته XML سفارشی استفاده کنید و فقط در صورت نیاز از XML Node بهره ببرید.

۳) استفاده همراه با HTTP Request برای SOAP

در SOAP معمولاً باید یک XML Envelope ارسال کنید. روال عملی:

Set: ساختن آبجکت JSON برای بدنه پیام (یا ساخت مستقیم متن XML)
XML (در صورت ساخت از JSON): تبدیل به XML
HTTP Request: تنظیم هدرها مثل Content-Type: text/xml; charset=utf-8 و در صورت نیاز SOAPAction

۴) عیب‌یابی سریع با نگه‌داری نسخه خام

قبل از تبدیل، یک کپی از XML خام را در یک فیلد مثل rawXml نگه دارید. این کار در زمان خطا کمک می‌کند دقیقاً بدانید چه چیزی وارد مرحله تبدیل شده است.

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

محدودیت‌ها

تبدیل XML به JSON همیشه یک نگاشت یک‌به‌یک کامل نیست؛ برخی جزئیات مثل ترتیب عناصر یا تفاوت متن/attribute ممکن است در JSON متفاوت نمایش داده شود.
XMLهای بسیار بزرگ می‌توانند باعث مصرف زیاد حافظه شوند؛ بهتر است داده را صفحه‌بندی کنید یا فقط بخش لازم را تبدیل کنید.
کار با namespaceها ممکن است مسیرهای دسترسی را پیچیده کند و نیاز به بررسی دقیق ساختار خروجی داشته باشد.

خطاهای رایج و راه‌حل‌ها

Invalid XML / Parse error
- علت: XML ناقص، وجود کاراکترهای غیرمجاز، یا قطع شدن داده
- راه‌حل: XML خام را لاگ کنید، معتبر بودن تگ‌ها و escape شدن کاراکترهای خاص را بررسی کنید.
Property not found
- علت: فیلد ورودی (Property Name) اشتباه انتخاب شده یا داده در مسیر دیگری است
- راه‌حل: در اجرای نود قبلی، مسیر دقیق داده را از Execution Data پیدا کنید و همان را وارد کنید (مثل body، data، response، xmlText).
خروجی غیرمنتظره (آرایه/آبجکت)
- علت: تکرارپذیری تگ‌ها در XML
- راه‌حل: گزینه Always Create Arrays را فعال کنید یا با Code ساختار را نرمال کنید.
به‌هم‌ریختگی حروف فارسی
- علت: Encoding نامناسب یا هدرهای اشتباه
- راه‌حل: UTF-8 را در کل مسیر رعایت کنید، در HTTP Request هدر charset را مشخص کنید، و از تبدیل‌های باینری نامطمئن پرهیز کنید.

ایده ها

ساخت مبدل خودکار فاکتور: دریافت XML فاکتور از ERP و ثبت آن در Google Sheets یا یک دیتابیس
مانیتورینگ RSS رقبا: تبدیل RSS به JSON، فیلتر کردن کلمات کلیدی، ارسال هشدار به Slack
تبدیل خروجی SOAP به گزارش روزانه: دریافت XML از وب‌سرویس، تبدیل به JSON، خلاصه‌سازی و ارسال ایمیل
استخراج اطلاعات از فایل‌های XML ارسالی مشتریان: دریافت فایل از ایمیل، تبدیل و اعتبارسنجی، سپس ثبت در CRM
ساخت سرویس میانی: گرفتن JSON از یک سیستم مدرن و تولید XML استاندارد برای یک سیستم قدیمی در یک ورکفلو

نود XML در N8N