همگام‌سازی فیلد Select جیرا با یک API خارجی: چرا نباید گزینه‌ها را حذف کنید

سناریو آشناست: یک فیلد Select در Jira دارید — فهرست شعبه‌ها، محصولات، مراکز هزینه — و منبع واقعی این فهرست جای دیگری است. یک سامانهٔ منابع انسانی، یک ERP، یا هر سرویسی که API دارد.

الان یک نفر دستی این فهرست را در Jira به‌روز نگه می‌دارد. تا وقتی فهرست ده‌تایی است مشکلی نیست. وقتی صدتایی شد و ماهی چندبار عوض شد، همیشه یک نفر یادش می‌رود.

سه راه، با سه هزینهٔ متفاوت

برای بیشتر موارد، گزینهٔ اول درست است — و کمترین چیزی است که می‌شکند. یک Scheduled Job که هر شب فهرست را می‌گیرد و گزینه‌ها را هماهنگ می‌کند، ۹۵ درصد ارزش را با ۱۰ درصد پیچیدگی می‌دهد.

مهم‌ترین تصمیم: disable، نه delete

این تک‌نکته، تفاوت یک همگام‌سازی سالم و یک فاجعهٔ آرام است.

وقتی گزینه‌ای از منبع خارجی حذف می‌شود — مثلاً شعبه‌ای بسته می‌شود — وسوسه این است که در Jira هم حذفش کنید. نکنید. Issueهایی که آن مقدار را دارند، مقدارشان را از دست می‌دهند. یعنی:

• تاریخچه ناقص می‌شود — نمی‌فهمید آن Issue مال کدام شعبه بود
• گزارش‌های قدیمی عوض می‌شوند و اعدادشان دیگر با نسخهٔ چاپ‌شده نمی‌خواند
• کوئری‌های JQL که آن مقدار را جست‌وجو می‌کنند، خطا می‌دهند

به‌جایش گزینه را غیرفعال کنید. گزینهٔ غیرفعال در فهرست کشویی به کاربر نشان داده نمی‌شود، ولی روی Issueهای قدیمی سر جایش می‌ماند و در JQL هم قابل جست‌وجوست. بهترین هر دو دنیا.

قاعده: چیزی که کاربر دیگر نباید انتخاب کند، غیرفعال می‌شود. چیزی که هرگز نباید وجود می‌داشت، حذف می‌شود. در همگام‌سازی، تقریباً همیشه حالت اول است.

منطق درست همگام‌سازی

الگوریتم سه شاخه دارد و هر سه لازم‌اند:

1. در API هست، در Jira نیست → گزینه را بساز
2. در هر دو هست → اگر در Jira غیرفعال بود، دوباره فعالش کن (شعبه‌ای که بازگشایی شده)
3. در Jira هست، در API نیست → غیرفعال کن، حذف نکن

شاخهٔ دوم را خیلی‌ها فراموش می‌کنند. بدون آن، گزینه‌ای که یک بار غیرفعال شده هرگز برنمی‌گردد و کاربر می‌گوید «شعبه هست ولی تو جیرا نیست».

محافظی که حتماً لازم دارید

این را قبل از هر کار دیگری بنویسید، نه بعدش:

اگر API خطا داد           → هیچ کاری نکن، خارج شو
اگر API فهرست خالی داد    → هیچ کاری نکن، خارج شو
اگر بیش از N درصد گزینه‌ها
   قرار است غیرفعال شوند   → متوقف شو و هشدار بده

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

اجرا: کنسول یا زمان‌بندی

دو حالت اجرا دارید و هر دو جا دارند:

• Script Console — برای همگام‌سازی یک‌باره یا وقتی می‌خواهید نتیجه را قبل از خودکارسازی ببینید
• Scheduled Job — برای اجرای شبانه. ساعت کم‌ترافیک انتخاب کنید، نه وسط روز

همیشه اول در حالت گزارش‌محض (dry run) اجرا کنید: اسکریپت بگوید چه چیزی می‌خواست عوض کند، بدون اینکه واقعاً عوض کند. اگر خروجی معقول بود، حالت واقعی را روشن کنید.

چند نکتهٔ عملیاتی

• ایندکس. بعد از تغییر گستردهٔ گزینه‌ها، اگر گزارش‌ها به‌روز نشدند، ایندکس را بررسی کنید.
• اعتبارنامه. توکن دسترسی به API خارجی را در متن اسکریپت ننویسید. جای امنی نگهش دارید که در بکاپ متنی لو نرود.
• لاگ. هر اجرا باید بنویسد چند گزینه ساخته، چند تا دوباره فعال و چند تا غیرفعال شده. بدون این، نمی‌فهمید همگام‌سازی اصلاً اجرا شده یا نه.
• سازگاری نسخه. مثل هر اسکریپت ScriptRunner، بعد از ارتقای بزرگ Jira دوباره تستش کنید.

جمع‌بندی

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

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