Skip to main content

Jira Integration

Connect NirmIQ to Atlassian Jira for change management and requirements traceability.

Subscription Required

Jira integration is gated at the Professional tier and above (100 syncs / month at Professional, 500 / month at Advanced, unlimited at Power and Enterprise).

Overview​

NirmIQ supports two levels of Jira integration:

  1. Global Jira Settings — Your default Jira credentials, used across all projects you participate in
  2. Project-Specific Jira Settings — Override credentials for a specific project (Admin only)

This flexible approach allows you to:

  • Work with multiple clients, each with their own Jira instance
  • Use your Global Jira for most projects, but a different Jira for specific projects
  • Automatically connect to the correct Jira based on the current project

Global Jira Settings​

What are Global Settings?​

Global Jira settings are your default credentials that apply to every project you belong to, unless that project has its own override.

How to Configure​

  1. Click your profile avatar in the top-right and choose Settings
  2. Open the Global Jira Settings section
  3. Fill in:
    • Jira Base URL: Your Jira instance URL (e.g., https://yourcompany.atlassian.net)
    • Email: Your Jira account email
    • API Token: Generate from Atlassian Account Settings
  4. Click Save Global Jira Settings
Generating an API Token
  1. Visit Atlassian Account Settings
  2. Click "Create API token"
  3. Give it a name (e.g., "NirmIQ Integration")
  4. Copy the token immediately (you won't see it again!)
  5. Paste into NirmIQ

Project-Specific Jira Settings (Admin Only)​

When to Use Project Settings?​

Use project-specific Jira when:

  • Working with multiple clients, each with their own Jira
  • A specific project needs different credentials than your Global Jira
  • A project requires the company / client Jira instead of your Global Jira

How to Configure​

  1. Select the project you want to configure from the header
  2. Click Project Settings → Integrations → Jira (only visible to Admins)
  3. Check "Enable project-specific Jira"
  4. Fill in the project's Jira credentials:
    • Jira Base URL: Client / project-specific Jira URL
    • Email: Email for this Jira instance
    • API Token: API token for this Jira instance
  5. Click Save Project Jira Settings
Status Badges
  • Active (blue badge) = Project is using project-specific Jira
  • Using Global (gray badge) = Project is falling back to your Global Jira

How Fallback Logic Works​

NirmIQ uses smart fallback to determine which Jira to connect to:

1. Check if project has project-specific Jira enabled
   ↓ YES → Use project Jira ✅
   ↓ NO  → Continue to step 2

2. Check if user has Global Jira configured
   ↓ YES → Use Global Jira ✅
   ↓ NO  → No Jira connection ❌

Example Scenarios​

Scenario 1: Global Jira Only​

  • Global Jira: https://yourorg.atlassian.net
  • Project A: No project settings → Uses Global Jira
  • Project B: No project settings → Uses Global Jira
  • Project C: No project settings → Uses Global Jira

Result: All projects use your Global Jira

Scenario 2: Mixed Configuration​

  • Global Jira: https://yourorg.atlassian.net
  • Project A: Project settings = https://clientx.atlassian.net → Uses Client X Jira
  • Project B: No project settings → Uses Global Jira
  • Project C: Project settings = https://clienty.jira.com → Uses Client Y Jira

Result: Each project connects to the correct Jira automatically.

Use Cases​

Use Case 1: Multi-Client Consulting Firm​

Company: A consulting firm working with 3 clients

Setup:

  • Global Jira: consulting-internal.atlassian.net
  • Project "Client X Requirements": clientx.atlassian.net
  • Project "Client Y Requirements": clienty.jira.com
  • Project "Internal Tools": Uses Global Jira (no override)

Benefits:

  • Engineers don't need to remember which Jira to use
  • Requirements automatically link to the correct client Jira
  • Internal projects use the company Jira

Use Case 2: Enterprise with Department Jiras​

Company: Large enterprise with department-specific Jira instances

Setup:

  • Global Jira: company.atlassian.net (default)
  • Project "HR System": hr.company.atlassian.net
  • Project "Finance System": finance.company.atlassian.net
  • Project "IT Tools": Uses Global Jira

Benefits:

  • Each department's requirements tracked in their own Jira
  • Cross-department projects use the company-wide Jira
  • Single sign-on across all projects

Features​

Linking Requirements to Jira Issues​

Once Jira is configured, you can:

  1. Link Requirement to Jira Issue:

    • Open requirement details
    • Click "Edit" to enter edit mode
    • Enter Jira issue key (e.g., PROJ-123)
    • NirmIQ fetches issue details automatically

  2. View Jira Issue Status:

    • See issue status in the requirements view
    • Track which requirements have associated Jira tickets
    • Monitor change request progress

Push to Jira (Create Issues)​

Create Jira issues directly from NirmIQ requirements:

  1. Select a Requirement that doesn't have a Jira issue linked
  2. Click "Push to Jira" in the Jira Issue panel
  3. Configure the Issue:
    • Select target Jira project from the dropdown
    • Choose issue type (Story, Task, Bug, etc.)
    • Set priority (optional)
    • Add custom labels (optional)
    • Add additional description / context (optional)
  4. Click "Create Issue"

What Gets Created​

When you push a requirement to Jira, NirmIQ creates an issue with:

  • Summary: [REQ-ID] Type: First 100 chars of requirement text
  • Description: Full requirement text with metadata (ID, type, status, version)
  • Labels:
    • nirmiq (identifies NirmIQ-created issues)
    • req-{custom-id} (links back to the requirement)
    • Any custom labels you add
  • Project & NirmIQ Link: The created issue is automatically linked back to the requirement
Best Practice

Use "Push to Jira" when you want to:

  • Create implementation tasks from requirements
  • Assign requirements to developers for execution
  • Track requirement implementation progress in Jira sprints

Multi-Team Support​

Push to Jira respects the multi-team settings hierarchy:

  1. Requirement-level override — If the requirement has a specific Jira instance
  2. Subsystem-level settings — Based on parent requirement
  3. Project-level settings — Project-specific Jira
  4. User-level settings — Your Global Jira fallback

This means different requirements in the same project can push to different Jira instances.

Push to Jira from Work Items​

You can also push to Jira directly from the Work Items panel:

  1. Open the Work Items panel from the sidebar
  2. Find the work item you want to push
  3. Click the Push to Jira button (only visible when Jira is configured and the item isn't already linked)
  4. Enter the Jira Project Key and select an Issue Type (Task, Story, or Bug)
  5. Click Create Issue

The work item is then linked to the Jira issue, and the Jira key appears as a clickable badge.

note

Work items can only be created for requirements with Approved or later status. See Work Items for details on the full lifecycle.

Troubleshooting​

"Failed to save Jira settings"​

Possible Causes:

  1. Invalid API token
  2. Incorrect Jira URL format
  3. Network connectivity issues

Solutions:

  • Verify the API token is correct and not expired
  • Ensure URL starts with https://
  • Check Jira URL is accessible from your browser

"Cannot fetch Jira issue"​

Possible Causes:

  1. Issue doesn't exist
  2. No permission to view the issue
  3. Wrong Jira instance

Solutions:

  • Verify the issue key is correct
  • Check you have permission in Jira
  • Ensure the correct Jira is configured for this project

Project Settings Not Visible​

Possible Causes:

  1. No project selected
  2. Not an Admin or Super Admin
  3. Project not loaded

Solutions:

  • Select a project from the header
  • Ask an Admin to grant you Admin permissions
  • Refresh the page

FAQ​

Q: Do I need both Global and project settings?​

A: No. Global settings alone work for most users. Project settings are only needed if different projects require different Jira instances.

Q: Can regular users configure project Jira?​

A: No. Only Admins and Super Admins can configure project-specific Jira settings.

Q: What happens if I disable project Jira?​

A: The project will fall back to your Global Jira settings automatically.

Q: Can I use the same Jira for all projects?​

A: Yes. Just configure Global Jira and don't set up any project-specific settings.

Q: How do I know which Jira is being used?​

A: Check the status badge in Project Jira Settings:

  • "Active" = Using project Jira
  • "Using Global" = Using your Global Jira

Security Notes​

  • API tokens are stored encrypted in the database
  • Tokens are transmitted over HTTPS only
  • Only you can see your Global Jira settings
  • Only Admins of your organisation can see project Jira settings
  • Jira credentials are never shared with other users