Skip to main content

Jira Integration

Pidima provides bidirectional integration with Jira, allowing you to import requirements and test cases from Jira issues and export Pidima artifacts back to Jira projects.

Overview​

The Jira integration supports:

  • OAuth 2.0 authentication with Atlassian Cloud
  • Import requirements and test cases from Jira using JQL queries
  • Export requirements and test cases to Jira as issues
  • Webhooks for real-time synchronization of changes
  • Default project mapping to streamline repeated operations

Setting Up the Connection​

Step 1: Authorize with Jira​

  1. Navigate to Project Settings → Integrations → Jira
  2. Click Connect to Jira
  3. You'll be redirected to Atlassian's OAuth consent screen
  4. Grant Pidima access to your Jira workspace
  5. After authorization, you're redirected back to Pidima with a success confirmation

Authorization can be scoped to:

  • Account level — All projects in the account share the same Jira connection
  • Project level — Each project has its own Jira connection

Step 2: Configure the Integration​

After authorization, create a Jira configuration:

  1. Click Add Configuration
  2. Select the Jira project from the dropdown (populated from your authorized Jira workspace)
  3. Configure field mappings (how Jira fields map to Pidima fields)
  4. Save the configuration

Step 3: Set Default Project (Optional)​

Set a default Jira project mapping for your Pidima project to skip project selection during import/export:

  1. Go to Project Settings → Jira → Default Project
  2. Select the Jira project to use by default
  3. Save

Importing from Jira​

Import Requirements​

  1. Navigate to Requirements → Import → From Jira
  2. Write a JQL query to select the issues you want to import (e.g., project = "PROJ" AND type = Story)
  3. Click Preview to see matching issues before importing
  4. Review the preview results — each Jira issue shows its key, summary, and status
  5. Select the target level in your Pidima project
  6. Click Import

Each imported Jira issue becomes a Pidima requirement with:

  • Name — From the Jira issue summary
  • Description — From the Jira issue description
  • External link — Reference back to the original Jira issue

Import Test Cases​

  1. Navigate to Test Cases → Import → From Jira
  2. Write a JQL query targeting test-related issues (e.g., project = "PROJ" AND type = "Test")
  3. Click Preview to verify results
  4. Click Import

JQL Validation​

Before running an import, you can validate your JQL query:

  • Click Validate to check syntax without executing the query
  • The validator reports any JQL errors with helpful messages

Exporting to Jira​

Export Requirements​

  1. Select requirements from the requirements list (checkboxes or bulk select)
  2. Click Export → To Jira
  3. Select the target Jira project (or use the default)
  4. Choose the issue type (Story, Task, Bug, etc.)
  5. Click Export

Each requirement is created as a Jira issue with:

  • Summary — From the requirement name
  • Description — From the requirement description
  • Priority — Mapped from the Pidima priority

Export Test Cases​

  1. Select test cases from the test cases list
  2. Click Export → To Jira
  3. Select the target Jira project and issue type
  4. Click Export

Webhooks​

Pidima can receive webhook events from Jira to stay synchronized:

  • Issue updated — When a Jira issue linked to a Pidima requirement changes, the requirement is flagged as unsynced
  • Issue deleted — Notifications when linked issues are removed

Configure webhooks in your Jira project settings to point to your Pidima instance's webhook endpoint.

Managing Configurations​

View and manage all Jira configurations for your account:

  • List configurations — See all active Jira connections
  • Update — Modify field mappings or project associations
  • Delete — Remove a configuration (does not delete imported data)
  • Revoke OAuth — Disconnect the Jira authorization entirely

Best Practices​

  • Use specific JQL — Narrow your JQL queries to import only relevant issues; avoid importing entire projects at once
  • Preview before importing — Always preview JQL results to verify you're importing the right issues
  • Set default projects — Configure default Jira project mappings to speed up repeated import/export workflows
  • Keep links — Imported requirements retain external links to their Jira source, enabling cross-reference
  • Use webhooks — Enable webhooks for projects where Jira issues change frequently to stay notified of upstream changes