جیرا

نود Jira چیست؟

نود Jira امکان اتصال و خودکارسازی فرآیندهای مدیریت پروژه و توسعه نرم‌افزار را در n8n فراهم می‌کند. Jira محصول شرکت Atlassian و استاندارد صنعت برای ردیابی Issue، مدیریت Agile و DevOps است.

قابلیت‌های کلیدی:

• مدیریت Issues: ایجاد، ویرایش، حذف، انتقال، assign و تغییر وضعیت issues
• جستجوی JQL: جستجوی پیشرفته با زبان Jira Query Language
• مدیریت Sprints: ایجاد sprint، انتقال issues و مدیریت backlog
• Boards: کار با Scrum و Kanban boards
• Epics: گروه‌بندی issues در epic‌های بزرگ
• Comments & Attachments: افزودن کامنت و پیوست به issues
• Watchers & Worklogs: مدیریت ناظران و ثبت زمان کار
• Workflow Transitions: انتقال issues بین وضعیت‌های مختلف (To Do → In Progress → Done)

نسخه‌های Jira:

• Jira Cloud: نسخه ابری (توصیه شده، REST API v3)
• Jira Server: نصب روی سرور شخصی (REST API v2)
• Jira Data Center: نسخه Enterprise با قابلیت clustering
• Jira Service Management: مدیریت خدمات IT (ITSM)

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

• Jira Cloud: Rate limiting بر اساس concurrent requests (نه تعداد کل)
• Jira Server/DC: قابل تنظیم توسط admin
• Pagination: حداکثر ۱۰۰ نتیجه در هر درخواست (پیش‌فرض ۵۰)
• JQL Queries: حداکثر ۱,۰۰۰ نتیجه در هر جستجو
• Attachment Size: حداکثر ۱۰ مگابایت در Jira Cloud

کاربردهای رایج

۱. ایجاد خودکار Issue از Alert‌های مانیتورینگ

وقتی سیستم مانیتورینگ (Grafana, PagerDuty, Datadog) alert ارسال کند، خودکار Issue در Jira ایجاد شود.

Webhook Trigger (alert از Grafana)
  → IF (severity = critical)
    → Jira (issue-create)
      Project: OPS
      Type: Bug
      Priority: Highest
      Summary: "🚨 Alert: {{$json.alertName}}"
      Description: "سرویس: {{$json.service}}\nوضعیت: {{$json.state}}\nزمان: {{$json.timestamp}}"
      Labels: ["monitoring", "auto-created"]
    → Slack (ارسال پیام به کانال on-call)

۲. همگام‌سازی با GitHub/GitLab

وقتی PR در GitHub ایجاد یا merge شود، وضعیت Issue مرتبط در Jira به‌روزرسانی شود.

GitHub Trigger (pull_request)
  → Code (استخراج Issue Key از branch name: feature/PROJ-123-fix-login)
  → IF (action = opened)
    → Jira (issue-transition: In Review)
    → Jira (issue-comment-add: "PR ایجاد شد: {{$json.pr_url}}")
  → IF (action = closed & merged)
    → Jira (issue-transition: Done)
    → Jira (issue-comment-add: "PR merge شد ✅")

۳. خودکارسازی Sprint Planning

شروع خودکار Sprint جدید و انتقال issues از Backlog.

Schedule (هر ۲ هفته - دوشنبه ساعت ۹)
  → Jira (issue-search-jql)
    JQL: "project = PROJ AND Sprint is EMPTY AND priority in (Highest, High) ORDER BY rank ASC"
  → Jira (sprint-create: Sprint جدید)
  → Loop (top 20 issues)
    → Jira (move to sprint)
  → Telegram (اعلان شروع Sprint به تیم)

۴. مانیتورینگ SLA و هشدار ددلاین

بررسی Issues نزدیک به ددلاین و ارسال هشدار.

Schedule (هر روز ساعت ۹)
  → Jira (issue-search-jql)
    JQL: "project = SUPPORT AND status != Done AND due <= 1d AND due >= -1d"
  → Loop
    → IF (due date = today)
      → Telegram (هشدار: "⚠️ Issue {{$json.key}} امروز ددلاین دارد!")
    → IF (due date = yesterday - overdue)
      → Jira (issue-update: priority = Highest)
      → Email (ارسال هشدار به manager)

۵. مسیریابی خودکار تیکت‌های مشتری (Jira Service Management)

تیکت‌های ورودی بر اساس نوع و محتوا به تیم مناسب ارجاع شوند.

Jira Trigger (Issue Created in Service Desk)
  → Code (تحلیل عنوان و توضیحات)
  → Switch
    → شامل "server" یا "downtime": assign به تیم DevOps
    → شامل "billing" یا "payment": assign به تیم مالی
    → شامل "feature" یا "request": assign به تیم محصول
    → default: assign به تیم Support
  → Jira (issue-assign + اضافه کردن component)
  → Jira (issue-comment-add: "تیکت به تیم {{$json.team}} ارجاع شد")

۶. مدیریت Release و نسخه‌ها

وقتی همه issues یک نسخه تکمیل شوند، خودکار release ساخته شود.

Schedule (هر ۶ ساعت)
  → Jira (issue-search-jql)
    JQL: "project = PROJ AND fixVersion = 'v2.1.0' AND status != Done"
  → IF (تعداد = 0 - همه تکمیل شده‌اند)
    → Jira (release version v2.1.0)
    → GitHub (create release tag)
    → Slack (اعلان release به تیم)
    → Email (release notes به مشتریان)

۷. ثبت خودکار زمان کار (Time Tracking)

از Toggl یا Clockify زمان‌ها را به Jira Worklog منتقل کنید.

Schedule (هر شب ساعت ۲۳)
  → Toggl (دریافت time entries امروز)
  → Loop
    → Code (استخراج Issue Key از description)
    → Jira (worklog-add)
      Issue: {{$json.issueKey}}
      TimeSpent: "{{$json.duration}}m"
      Comment: "{{$json.description}}"
      Started: {{$json.start}}

۸. Bug Triage خودکار

باگ‌های جدید بر اساس severity خودکار دسته‌بندی و اولویت‌بندی شوند.

Jira Trigger (Issue Created, type = Bug)
  → Code (تحلیل عنوان و description)
  → Switch (بر اساس کلمات کلیدی)
    → "crash" یا "data loss": Priority = Highest, Label = "critical"
    → "slow" یا "performance": Priority = High, Label = "performance"
    → "UI" یا "display": Priority = Medium, Label = "ui-bug"
    → default: Priority = Low
  → Jira (issue-update: priority + labels)
  → IF (critical)
    → Jira (issue-assign: senior developer)
    → Slack (alert فوری به کانال #incidents)

۹. یکپارچه‌سازی با DevOps Pipeline

پس از موفقیت CI/CD، وضعیت Issue در Jira به‌روزرسانی شود.

Webhook (از Jenkins/GitLab CI)
  → Code (استخراج Issue Keys از commit messages)
  → Loop
    → IF (build success)
      → Jira (issue-transition: Ready for QA)
      → Jira (issue-comment-add: "Build #{{$json.buildNumber}} deployed to staging ✅")
    → IF (build failed)
      → Jira (issue-comment-add: "Build failed ❌: {{$json.error}}")
      → Jira (issue-transition: In Progress)

۱۰. گزارش هفتگی Sprint Progress

هر هفته گزارش پیشرفت Sprint ساخته و ارسال شود.

Schedule (جمعه ساعت ۱۷)
  → Jira (sprint-issues: active sprint)
  → Code (محاسبه آمار)
    - تعداد کل issues
    - Done / In Progress / To Do
    - Story Points completed vs total
    - Bugs found vs fixed
  → Telegram (ارسال گزارش با نمودار)
  → Notion (ایجاد صفحه گزارش)

۱۱. ایجاد Jira Issue از Slack

با ارسال پیام در Slack، خودکار Issue در Jira ایجاد شود.

Slack Trigger (reaction_added: 🎫)
  → Slack (دریافت متن پیام)
  → Jira (issue-create)
    Summary: "از Slack: {{$json.text.substring(0, 100)}}"
    Description: "ارسال‌کننده: {{$json.user}}\nکانال: {{$json.channel}}\n\n{{$json.text}}"
    Labels: ["from-slack"]
  → Slack (reply: "Issue {{$json.key}} ایجاد شد ✅")

نکات حرفه‌ای

۱. JQL (Jira Query Language) - زبان جستجوی قدرتمند

JQL قلب جستجو در Jira است. نمونه‌های کاربردی:

// Issues باز من در پروژه خاص
project = PROJ AND assignee = currentUser() AND status != Done

// باگ‌های بحرانی ۷ روز اخیر
type = Bug AND priority = Highest AND created >= -7d

// Issues بدون assignee در Sprint فعال
Sprint in openSprints() AND assignee is EMPTY

// جستجو در متن
summary ~ "login" OR description ~ "authentication"

// Issues به‌روزرسانی شده این هفته
updated >= startOfWeek()

// ترکیب پیشرفته
project in (PROJ, DEV) AND type in (Bug, Task) AND status changed to "Done" DURING (startOfMonth(), now())

۲. توابع JQL کاربردی

currentUser()              → کاربر فعلی
now()                      → زمان فعلی
startOfDay() / endOfDay()  → شروع/پایان روز
startOfWeek()              → شروع هفته
startOfMonth()             → شروع ماه
membersOf("team-name")     → اعضای گروه
openSprints()              → Sprint‌های باز
closedSprints()            → Sprint‌های بسته

۳. Atlassian Document Format (ADF) در Jira Cloud

Jira Cloud API v3 از ADF برای description و comment استفاده می‌کند:

{
  "type": "doc",
  "version": 1,
  "content": [
    {
      "type": "paragraph",
      "content": [{"type": "text", "text": "متن ساده"}]
    },
    {
      "type": "heading",
      "attrs": {"level": 2},
      "content": [{"type": "text", "text": "عنوان"}]
    },
    {
      "type": "codeBlock",
      "attrs": {"language": "javascript"},
      "content": [{"type": "text", "text": "console.log('hello')"}]
    }
  ]
}

۴. Custom Fields - شناسایی و استفاده

برای یافتن ID فیلدهای سفارشی:

GET /rest/api/3/field
→ نتیجه: {"id": "customfield_10001", "name": "Story Points", "schema": {"type": "number"}}

سپس در ایجاد/ویرایش Issue:

{
  "fields": {
    "customfield_10001": 5,
    "customfield_10002": {"value": "Frontend"},
    "customfield_10003": [{"value": "Tag1"}, {"value": "Tag2"}]
  }
}

۵. Workflow Transitions - دریافت و استفاده

ابتدا transitions مجاز را بگیرید:

GET /rest/api/3/issue/PROJ-123/transitions
→ [{"id": "21", "name": "In Progress"}, {"id": "31", "name": "Done"}]

سپس transition انجام دهید:

POST /rest/api/3/issue/PROJ-123/transitions
{"transition": {"id": "31"}, "fields": {"resolution": {"name": "Fixed"}}}

۶. Bulk Operations برای عملیات دسته‌ای

برای تغییرات انبوه از Loop و Wait استفاده کنید:

Jira (JQL search) → Split In Batches (10) → Loop → Jira (update) → Wait (500ms) → Next

۷. Webhook‌های Jira برای Real-time

بجای polling، از Jira Webhooks استفاده کنید:

• System Webhooks (Admin): برای تمام events
• Issue Webhooks: فقط events خاص
• events مهم: jira:issue_created, jira:issue_updated, sprint_started, sprint_closed
• JQL Filter برای webhook: فقط events مطابق با کوئری JQL ارسال شوند

۸. Account ID بجای Username (Jira Cloud)

در Jira Cloud، از Account ID استفاده کنید (GDPR compliance):

// قدیمی (Server): "assignee": {"name": "john.doe"}
// جدید (Cloud): "assignee": {"accountId": "5b10ac8d82e05b22cc7d4ef5"}

Account ID را از /rest/api/3/user/search?query=john بگیرید.

۹. Pagination برای نتایج زیاد

JQL حداکثر ۱,۰۰۰ نتیجه برمی‌گرداند. برای همه نتایج:

startAt=0, maxResults=100 → نتایج ۱ تا ۱۰۰
startAt=100, maxResults=100 → نتایج ۱۰۱ تا ۲۰۰
... تا وقتی total > startAt + maxResults

۱۰. Labels vs Components vs Fix Versions

• Labels: برچسب‌های آزاد، همه می‌توانند ایجاد کنند (مثل: "urgent", "backend")
• Components: بخش‌های پروژه، فقط admin تعریف می‌کند (مثل: "API", "Frontend", "Database")
• Fix Versions: نسخه‌های نرم‌افزار (مثل: "v2.0", "v2.1") - برای release planning

۱۱. Jira Service Management (JSM) Tips

• از Request Types برای دسته‌بندی تیکت‌ها استفاده کنید
• SLA‌ها خودکار محاسبه می‌شوند - از JQL برای مانیتورینگ استفاده کنید
• Customer Portal جدا از Agent view است
• /rest/servicedeskapi/ endpoint جداگانه برای JSM

۱۲. Branch Name Convention

از نام Issue در branch names استفاده کنید تا integration خودکار شود:

feature/PROJ-123-add-login-page
bugfix/PROJ-456-fix-null-pointer
hotfix/PROJ-789-security-patch

Jira خودکار branch را به Issue لینک می‌کند.

۱۳. Automation Rules داخلی Jira

ترکیب Automation Rules Jira با n8n:

• از Jira Automation برای عملیات ساده درون Jira
• از n8n برای عملیات cross-platform (Jira + Slack + GitHub + Email)

۱۴. Issue Link Types

Issues را به هم مرتبط کنید:

"blocks" / "is blocked by"
"duplicates" / "is duplicated by"
"clones" / "is cloned by"
"relates to"

۱۵. Epic Management

Epic‌ها برای گروه‌بندی issues مرتبط:

// ایجاد Epic
Jira (issue-create): type = Epic, customfield_10011 (Epic Name) = "Feature X"

// اضافه کردن Issue به Epic (Cloud)
Jira (issue-update): parent = {"key": "PROJ-100"}

// لیست issues یک Epic
Jira (JQL): "Epic Link" = PROJ-100 OR parent = PROJ-100

۱۶. Notify Parameter

با notifyUsers: false از ارسال اعلان‌های اضافی جلوگیری کنید - مخصوصاً در عملیات bulk مفید است.

رفع مشکلات رایج

❌ خطای 401 Unauthorized

علت: اطلاعات احراز هویت نامعتبر

راه‌حل

• Jira Cloud: مطمئن شوید Email و API Token صحیح هستند
• API Token را regenerate کنید (ممکن است revoke شده باشد)
• Domain را بررسی کنید (your-company.atlassian.net بدون https://)
• Jira Server: Username و Password/PAT را بررسی کنید
• Basic Auth header باید base64-encoded باشد

❌ خطای 403 Forbidden

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

راه‌حل

• مطمئن شوید کاربر مجوز لازم در پروژه را دارد
• برای ایجاد Issue، نیاز به permission "Create Issues" دارید
• برای Transition، نیاز به permission "Transition Issues" دارید
• برای حذف، نیاز به permission "Delete Issues" دارید
• از admin بخواهید permissions را بررسی کند
• در Jira Cloud، OAuth scopes کافی باشد

❌ خطای 404 Not Found

علت: Issue، پروژه یا Resource پیدا نشد

راه‌حل

• کلید Issue را بررسی کنید (PROJ-123 نه فقط 123)
• مطمئن شوید پروژه وجود دارد و حذف نشده
• برای Jira Cloud، Account ID بجای Username استفاده کنید
• API version (v2 vs v3) را بررسی کنید
• URL endpoint صحیح باشد

❌ خطای 400 Bad Request - فیلدهای اجباری

علت: فیلدهای required پر نشده یا فرمت نادرست

راه‌حل

• هر Issue Type فیلدهای اجباری متفاوتی دارد
• summary و issuetype و project همیشه اجباری هستند
• Custom fields را با customfield_XXXXX ارسال کنید
• برای ADF (Atlassian Document Format) در Cloud، فرمت JSON صحیح استفاده کنید
• Screen scheme ممکن است فیلدهای اضافی اجباری کرده باشد

❌ خطای Transition نامعتبر

علت: Transition ID اشتباه یا transition در وضعیت فعلی مجاز نیست

راه‌حل

• ابتدا transitions مجاز را بگیرید: GET /rest/api/3/issue/{issueKey}/transitions
• هر وضعیت فقط transitions مشخصی دارد (بر اساس Workflow)
• Transition ID عددی است (مثل: "21", "31")
• بررسی کنید آیا transition نیاز به فیلد اجباری دارد (مثل Resolution)
• Workflow conditions ممکن است transition را block کنند

❌ خطای Custom Field نامعتبر

علت: نام یا مقدار Custom Field اشتباه

راه‌حل

• Custom fields با customfield_XXXXX شناخته می‌شوند
• برای یافتن ID: GET /rest/api/3/field لیست تمام فیلدها
• هر نوع Custom Field فرمت مقدار متفاوتی دارد:
• Single Select: {"value": "Option"}
• Multi Select: [{"value": "Opt1"}, {"value": "Opt2"}]
• User Picker: {"accountId": "..."}
• Date: "2024-01-15"
• Number: 42
• Cascading Select: {"value": "Parent", "child": {"value": "Child"}}

❌ خطای Rate Limiting (429)

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

راه‌حل

• Jira Cloud از concurrent rate limiting استفاده می‌کند
• بین درخواست‌ها Wait node اضافه کنید (حداقل 500ms)
• header Retry-After را بررسی و رعایت کنید
• عملیات batch را به قطعات کوچکتر تقسیم کنید
• از Retry on Fail در n8n استفاده کنید

❌ JQL Syntax Error

علت: خطای نحوی در کوئری JQL

راه‌حل

• مقادیر رشته‌ای را در double quote بگذارید: status = "In Progress"
• نام فیلدها با فاصله باید در double quote باشند: "Story Points" > 5
• از reserved words در مقادیر با quote استفاده کنید
• عملگرهای مجاز: =, !=, >, <, >=, <=, ~ (contains), in, not in, is, is not
• تاریخ‌ها: created >= "2024-01-01" یا created >= -7d