Catalio logo
Sign in

Integrations

Jira Integration

Bridge the gap between requirements management and agile development by connecting Catalio to Jira. This integration enables seamless synchronization between Catalio’s structured requirements and Jira’s powerful project management capabilities, ensuring your development team always works on the right priorities with complete traceability.

Overview

Why Connect Catalio to Jira?

The Catalio-Jira integration solves a critical challenge in modern software development: maintaining alignment between business requirements and development execution. While Catalio excels at capturing, analyzing, and managing requirements with AI-powered insights, Jira is the industry standard for agile development workflow management.

Key Benefits:

  • Automatic Synchronization: Requirements defined in Catalio automatically create corresponding Jira issues, eliminating manual data entry
  • Bi-directional Updates: Status changes in either system reflect in the other, providing real-time visibility
  • Hierarchy Mapping: Catalio’s requirement structure maps intelligently to Jira’s epic/story/task hierarchy
  • Sprint Planning Integration: Use Catalio requirements directly in Jira sprint planning
  • Complete Traceability: Track implementation progress from initial requirement through deployment
  • Reduced Context Switching: Teams work in their preferred tools while maintaining data consistency

How the Integration Works

The integration operates on a sophisticated mapping system that respects the workflows of both platforms:

  1. Requirements become Jira Issues: Each Catalio requirement can be synced as a Jira Epic, Story, or Task based on your configuration
  2. Smart Hierarchy: Requirement relationships map to Jira’s parent-child structure
  3. Field Mapping: Catalio metadata (priority, status, assignee) synchronizes with corresponding Jira fields
  4. Custom Fields: Organization-specific Jira fields can be mapped to Catalio attributes
  5. Webhook Communication: Both systems notify each other of changes in real-time
  6. Conflict Resolution: Smart merge strategies handle simultaneous updates

Supported Jira Versions

  • Jira Cloud: Full support for all Jira Cloud editions
  • Jira Server: Version 8.0 and above
  • Jira Data Center: All versions with API access enabled

Prerequisites

Jira Configuration Requirements

Before enabling the integration, ensure your Jira instance meets these requirements:

For Jira Cloud:

  • Administrator access to your Jira Cloud site
  • Ability to create API tokens in Atlassian Account settings
  • At least one Jira project with appropriate permission schemes
  • Jira Software or Jira Work Management license (Core edition has limited API)

For Jira Server/Data Center:

  • Jira version 8.0 or higher
  • REST API enabled (default in most installations)
  • User account with project administration permissions
  • Network connectivity from Catalio servers to your Jira instance
  • SSL/TLS certificate configured (recommended for security)

Permission Requirements

The Jira user account used for integration needs these specific permissions:

Project Permissions:

  • Browse Projects
  • Create Issues
  • Edit Issues
  • Delete Issues (optional, for cleanup operations)
  • Manage Sprints (if using sprint sync)
  • Administer Projects (for custom field mapping setup)

Global Permissions:

  • Create Shared Objects (for filters and dashboards)
  • Bulk Change (for efficient multi-requirement syncs)

Network and Security

For Cloud Installations:

  • No special network configuration required
  • Catalio uses HTTPS for all Jira Cloud communication
  • OAuth 2.0 or API token authentication supported

For Self-Hosted Jira:

  • Ensure Jira’s REST API is accessible from Catalio servers
  • Whitelist Catalio IP addresses in firewall if needed
  • Configure reverse proxy if Jira is behind corporate firewall
  • SSL certificate must be valid (not self-signed, unless added to trust store)

Authentication

Jira Cloud Authentication

Jira Cloud supports two authentication methods. We recommend API tokens for simplicity and OAuth 2.0 for enterprise deployments.

Method 1: API Token (Recommended for Most Users)

Step 1: Generate API Token

  1. Log into your Atlassian account at id.atlassian.com
  2. Navigate to Security → API tokens
  3. Click Create API token
  4. Provide a descriptive label: “Catalio Integration - Production”
  5. Click Create and copy the token immediately (shown only once)

Step 2: Configure in Catalio

  1. Navigate to Settings → Integrations → Jira
  2. Select Jira Cloud
  3. Enter your configuration:
    • Site URL: Your Jira Cloud URL (e.g., yourcompany.atlassian.net)
    • Email: Your Atlassian account email
    • API Token: Paste the token from Step 1
  4. Click Test Connection to verify
  5. Click Save & Enable to activate the integration

Security Best Practices:

  • Store the API token securely (Catalio encrypts tokens at rest)
  • Use a dedicated service account email rather than personal accounts
  • Rotate tokens every 90 days for compliance
  • Revoke immediately if compromised

Method 2: OAuth 2.0 (Enterprise Recommended)

OAuth provides more granular permission control and doesn’t require sharing credentials.

Step 1: Register OAuth App

  1. Go to developer.atlassian.com/console
  2. Click Create → OAuth 2.0 integration
  3. Fill in the details:
    • Name: “Catalio Requirements Integration”
    • App type: Server-side application
  4. Configure OAuth settings:
    • Redirect URL: https://your-catalio-instance.com/integrations/jira/oauth/callback
    • Scopes: Select these scopes:
      • read:jira-work
      • write:jira-work
      • read:jira-user
      • offline_access (for refresh tokens)
  5. Save and copy your Client ID and Client Secret

Step 2: Connect from Catalio

  1. In Catalio: Settings → Integrations → Jira
  2. Select Jira Cloud (OAuth)
  3. Enter Client ID and Client Secret
  4. Click Authorize with Jira
  5. Complete Atlassian’s consent screen
  6. You’ll be redirected back to Catalio with confirmation

Jira Server/Data Center Authentication

Self-hosted Jira uses basic authentication with username and password or personal access tokens.

Basic Authentication Setup

Step 1: Create Service Account (Recommended)

Create a dedicated Jira user for the integration rather than using personal credentials:

  1. In Jira: Settings (gear icon) → User Management
  2. Click Create User
  3. Fill in details:
    • Email: catalio-integration@yourcompany.com
    • Username: catalio-service
    • Full Name: “Catalio Integration Service”
  4. Assign to appropriate groups with project permissions
  5. Set a strong password

Step 2: Configure in Catalio

  1. Navigate to Settings → Integrations → Jira
  2. Select Jira Server/Data Center
  3. Enter configuration:
    • Jira URL: Your self-hosted URL (e.g., https://jira.yourcompany.com)
    • Username: Service account username
    • Password: Service account password
  4. Click Test Connection
  5. Click Save & Enable

Personal Access Tokens (Jira 8.14+)

For Jira Server/Data Center 8.14 and above, personal access tokens provide better security:

  1. In Jira: User Profile → Personal Access Tokens
  2. Click Create token
  3. Name: “Catalio Integration”
  4. Expiry: Set based on your security policy (recommend 1 year max)
  5. Copy the generated token

In Catalio:

  1. Select Jira Server/Data Center (Token Auth)
  2. Enter Jira URL and Personal Access Token
  3. Test and enable

Project Mapping

Understanding Project Relationships

The integration maps Catalio projects to Jira projects, establishing a many-to-one or one-to-one relationship depending on your organizational structure:

One-to-One Mapping:

  • Best for teams with dedicated Jira projects per product
  • Example: Catalio “Mobile App 2.0” → Jira “MOBILE” project

Many-to-One Mapping:

  • Useful when multiple Catalio requirement projects feed into a single development backlog
  • Example: Catalio “Customer Requests”, “Internal Initiatives” → Jira “DEVELOPMENT” project

Advanced Mapping:

  • Map different requirement categories to different Jira projects
  • Example: Security requirements → “SECURITY” project, Features → “FEATURES” project

Initial Project Mapping

Step 1: Select Catalio Project

  1. Navigate to your Catalio project
  2. Go to Project Settings → Integrations → Jira
  3. Click Configure Jira Mapping

Step 2: Choose Jira Project

  1. From the dropdown, select the target Jira project
    • The list shows all projects you have access to
    • Projects display with their key (e.g., “Product Development (PROD)”)
  2. Select issue type defaults:
    • Default Issue Type: Story (typical for most requirements)
    • Alternative Types: Configure rules for different requirement types

Step 3: Configure Hierarchy Rules

Define how Catalio’s requirement hierarchy maps to Jira:

Catalio Structure              Jira Structure

├─ Epic Requirement      →     Epic

   ├─ Feature Requirement →    Story (links to Epic)

      ├─ Technical Req    →    Sub-task (child of Story)

Configuration options:

  • Top-level requirements: Epic or Story
  • Child requirements: Story, Sub-task, or Task
  • Nested children: Sub-task only (Jira limitation)

Step 4: Define Sync Direction

Choose synchronization behavior:

  • One-Way (Catalio → Jira): Requirements create Jira issues, but Jira changes don’t update Catalio
  • Bi-Directional: Changes in either system sync to the other (recommended)
  • Jira as Source of Truth: Catalio requirements stay read-only, Jira is authoritative

Step 5: Initial Sync

After configuration, perform the initial synchronization:

  1. Review the mapping preview showing which requirements will create which issues
  2. Optionally filter requirements by status or label for selective sync
  3. Click Start Initial Sync
  4. Monitor progress in the sync status panel
  5. Review any conflicts or errors in the sync report

Advanced Mapping Scenarios

Scenario 1: Epic-Story-Task Hierarchy

For teams using full Jira hierarchy:

Mapping Configuration:

  Catalio Requirement Type: "Epic"

    → Jira Issue Type: Epic



  Catalio Requirement Type: "Feature"

    → Jira Issue Type: Story

    → Link to parent Epic: Yes



  Catalio Requirement Type: "Technical"

    → Jira Issue Type: Sub-task

    → Parent: Story

Scenario 2: Flat Structure with Labels

For teams preferring flat backlogs with labels:

Mapping Configuration:

  All Requirements → Jira Issue Type: Story

  Catalio Categories → Jira Labels

  Catalio Priority → Jira Priority

  No parent-child linking

Scenario 3: Multi-Project Routing

Route different requirement types to different Jira projects:

Mapping Rules:

  If requirement.category = "Security":

    → Jira Project: SEC

    → Issue Type: Security Story



  If requirement.category = "Feature":

    → Jira Project: PROD

    → Issue Type: Story



  If requirement.category = "Bug":

    → Jira Project: MAINT

    → Issue Type: Bug

Configure this under Advanced Mapping Rules using the rule builder interface.

Requirement Synchronization

Converting Requirements to Jira Issues

When a Catalio requirement syncs to Jira, the system intelligently maps fields to create meaningful issues:

Core Field Mapping

Requirement Title → Issue Summary

Catalio: "User Authentication via SSO"

Jira:    "User Authentication via SSO"

Requirement Description → Issue Description

Catalio’s rich text description converts to Jira’s format (Markdown for Cloud, Wiki for Server):

Catalio Description (Markdown):



## Overview



Users need single sign-on capability...



## Acceptance Criteria



- [ ] Google OAuth integration

- [ ] SAML 2.0 support



Jira Description: h2. Overview Users need single sign-on capability...



h2. Acceptance Criteria



- Google OAuth integration

- SAML 2.0 support

Requirement Metadata

Catalio Field Jira Field Notes
Priority Priority Maps High→High, Medium→Medium, Low→Low
Status Status Configurable status mapping
Assignee Assignee Syncs if user exists in both systems
Due Date Due Date Direct date sync
Labels Labels All Catalio labels sync as Jira labels
Category Component Optional mapping to Jira components

Requirement Status Synchronization

Status mapping is configurable to match your workflows:

Default Mapping:

Catalio Status    → Jira Status ───────────────────────────────── Draft            → To Do In

Review        → In Progress Approved         → To Do In Development   → In Progress

Completed        → Done Archived         → (No sync)

Custom Mapping Example:

For teams with custom Jira workflows:

Catalio Status       → Jira Status ────────────────────────────────────── Draft               →

Backlog Needs Refinement    → Refinement Ready for Planning  → Ready In Sprint           → In

Progress In QA              → Testing Done               → Closed

Configure custom mappings in Project Settings → Jira Integration → Status Mapping.

Bi-Directional Synchronization

When bi-directional sync is enabled, changes flow both ways:

Catalio → Jira Updates

These changes trigger immediate Jira updates:

  • Title change: Updates Jira issue summary
  • Description edit: Syncs to Jira description (smart merge preserves Jira-specific content)
  • Status change: Updates Jira workflow status (if transition is valid)
  • Assignment change: Updates Jira assignee
  • Priority change: Updates Jira priority
  • Label addition/removal: Adds/removes Jira labels
  • Requirement deletion: Archives Jira issue (doesn’t delete by default)

Jira → Catalio Updates

These Jira changes update Catalio requirements:

  • Status transition: Updates requirement status per mapping
  • Assignment change: Updates requirement assignee
  • Description edit: Smart merge updates requirement description
  • Comment added: Creates comment in Catalio (if enabled)
  • Issue linked: Creates relationship in Catalio
  • Sprint assigned: Updates requirement sprint field
  • Resolution set: Updates requirement resolution status

Conflict Resolution

When both systems are edited simultaneously:

Automatic Resolution:

  • Last write wins for simple fields (title, priority, labels)
  • Additive merge for comments and attachments
  • Smart merge for descriptions (preserves unique content from both)

Manual Resolution Required:

  • Status conflicts (both systems changed status differently)
  • Assignment conflicts (assigned to different people)
  • Critical field changes flagged by custom rules

Conflicts appear in Integration Dashboard → Sync Conflicts for review.

Sync Triggering

Synchronization can be triggered in several ways:

Automatic Sync (Real-time):

  • Triggered by webhooks from both systems
  • Updates typically appear within 5-30 seconds
  • Requires webhook configuration (see Advanced Setup)

Scheduled Sync:

  • Runs every 15 minutes by default
  • Catches any missed webhook events
  • Configurable interval: 5 minutes to 24 hours

Manual Sync:

  • Click Sync Now in requirement details or project dashboard
  • Useful for testing or recovering from errors
  • Can sync individual requirement or entire project

Bulk Sync:

  • Select multiple requirements and choose Sync to Jira
  • Efficient for initial setup or after configuration changes
  • Queued as background job for large batches

Handling Sync Errors

Common sync errors and resolutions:

“User not found in Jira”

  • Occurs when Catalio assignee doesn’t exist in Jira
  • Resolution: Map users, create Jira user, or remove assignee constraint

“Invalid status transition”

  • Jira workflow doesn’t allow the status change
  • Resolution: Adjust status mapping or modify Jira workflow

“Permission denied”

  • Integration user lacks necessary permissions
  • Resolution: Grant appropriate project permissions in Jira

“Custom field required”

  • Jira project requires fields not mapped from Catalio
  • Resolution: Set default values or add field mapping

View detailed error logs in Integration Dashboard → Sync History → Error Details.

Custom Field Mapping

Understanding Custom Fields

Both Catalio and Jira support custom fields for organization-specific metadata. The integration enables mapping between these fields to preserve important information during sync.

Use Cases:

  • Regulatory compliance tracking (e.g., “HIPAA Impact” field)
  • Business metadata (e.g., “Revenue Impact”, “Customer Segment”)
  • Technical details (e.g., “Architecture Layer”, “Technology Stack”)
  • Project management (e.g., “T-Shirt Size”, “Story Points”)

Setting Up Custom Field Mapping

Step 1: Identify Fields

In Catalio:

  1. Navigate to Settings → Custom Fields
  2. Note the field names and types you want to sync
  3. Example: “Customer Impact” (dropdown), “Story Points” (number)

In Jira:

  1. Go to Settings → Issues → Custom Fields
  2. Identify corresponding fields
  3. Note the field IDs (shown in URL when editing)

Step 2: Create Mapping

  1. In Catalio: Settings → Integrations → Jira → Custom Fields
  2. Click Add Field Mapping
  3. Configure mapping:
Example Mapping 1: Dropdown to Select List

─────────────────────────────────────────

Catalio Field: "Customer Impact"

  Type: Dropdown

  Values: Critical, High, Medium, Low



Jira Field: "Business Impact"

  Type: Select List (single choice)

  Field ID: customfield_10001



Value Mapping:

  Critical → Critical

  High     → High

  Medium   → Medium

  Low      → Minor



Example Mapping 2: Numeric Fields

──────────────────────────────────

Catalio Field: "Story Points"

  Type: Number



Jira Field: "Story Points"

  Type: Number

  Field ID: customfield_10002



Value Mapping: Direct (no transformation)

Step 3: Set Sync Direction

For each mapping, choose direction:

  • One-way (Catalio → Jira): Catalio is the source of truth
  • Bi-directional: Keep both systems in sync
  • One-way (Jira → Catalio): Jira is the source of truth

Step 4: Handle Missing Values

Define behavior when values don’t map:

  • Use Default: Set a default Jira value
  • Skip Field: Don’t update this field
  • Create Value: Automatically create new Jira option (for select lists)
  • Reject Sync: Mark as error and require manual resolution

Common Custom Field Scenarios

Story Points Sync

Essential for agile teams using points for estimation:

Mapping Configuration:

  Catalio: "Estimated Effort" (Number, 0-100)

  Jira: "Story Points" (Number, customfield_10002)

  Direction: Jira → Catalio (Jira is source of truth for estimates)

  Transform: Direct copy

Why Jira → Catalio? Development teams typically estimate in Jira during sprint planning, so Jira should be authoritative for this field.

Business Value Tracking

For prioritization based on business value:

Mapping Configuration:

  Catalio: "Business Value Score" (Number, 1-100)

  Jira: "Value Score" (Number, customfield_10003)

  Direction: Catalio → Jira (Business analysts work in Catalio)

  Transform: Direct copy

Multi-Select Fields

Handling fields with multiple values:

Mapping Configuration:

  Catalio: "Affected Systems" (Multi-select)

    Values: API, Database, UI, Mobile, Integration



  Jira: "Components" (Component field)

    Components: API, Database, Frontend, Mobile App, External



  Value Mapping:

    API         → API

    Database    → Database

    UI          → Frontend

    Mobile      → Mobile App

    Integration → External



  Direction: Bi-directional

  On Conflict: Merge (union of both selections)

Date Fields

Syncing important dates:

Example 1: Target Release Date

────────────────────────────────

Catalio: "Target Release" (Date)

Jira: "Fix Version/s" (Version field)

Transform: Convert date to matching version name

Logic: Match Catalio date to Jira version with closest release date



Example 2: Regulatory Deadline

───────────────────────────────

Catalio: "Compliance Deadline" (Date)

Jira: "Due Date" (Date)

Transform: Direct copy

Direction: Catalio → Jira (Compliance team manages in Catalio)

Text Fields with Validation

For fields requiring specific formats:

Mapping Configuration:

  Catalio: "API Endpoint" (Text)

    Validation: Must start with "/"



  Jira: "Technical Spec" (Text, customfield_10004)



  Transform:

    - Extract API endpoint from Catalio field

    - Append to Jira technical spec as structured section

    - Format: "API: {endpoint}"

Advanced Transformations

For complex mapping logic, use transformation rules:

Calculated Fields:

// Transform Catalio priority + impact to Jira custom priority

Source Fields:

  - catalio.priority (High/Medium/Low)

  - catalio.customer_impact (Critical/High/Medium/Low)



Target Field:

  - jira.custom_priority (P0/P1/P2/P3)



Transform Logic:

  if (catalio.priority === "High" && catalio.customer_impact === "Critical")

    return "P0"

  else if (catalio.priority === "High" || catalio.customer_impact === "Critical")

    return "P1"

  else if (catalio.priority === "Medium")

    return "P2"

  else

    return "P3"

Concatenated Fields:

// Combine multiple Catalio fields into Jira description

Source Fields:

  - catalio.description

  - catalio.assumptions (JSON)

  - catalio.constraints (JSON)



Target Field:

  - jira.description



Transform Logic:

  description = catalio.description



  if (catalio.assumptions) {

    description += "\n\nAssumptions:\n"

    description += formatList(catalio.assumptions)

  }



  if (catalio.constraints) {

    description += "\n\nConstraints:\n"

    description += formatList(catalio.constraints)

  }



  return description

Configure advanced transformations using JavaScript expressions in Custom Field Mapping → Advanced Transforms.

Status Synchronization

Workflow Alignment

Effective status synchronization requires understanding and mapping the workflows in both systems.

Typical Catalio Requirement Workflow:

Draft → In Review → Approved → In Development → In Testing → Completed

  ↓

Rejected (terminal)

Typical Jira Development Workflow:

Backlog → To Do → In Progress → Code Review → Testing → Done

  ↓

Won't Do (terminal)

Status Mapping Strategies

Strategy 1: Direct Mapping

Best for teams with similar workflows in both systems:

Catalio Status    → Jira Status ───────────────────────────────── Draft            → Backlog In

Review        → To Do Approved         → To Do In Development   → In Progress In Testing       →

Testing Completed        → Done Rejected         → Won't Do

Configuration:

  1. Settings → Jira Integration → Status Mapping
  2. Select Direct Mapping mode
  3. Map each Catalio status to equivalent Jira status
  4. Test with sample requirement

Strategy 2: Phase-Based Mapping

For teams with different granularity in each system:

Catalio Phase          → Jira Status

───────────────────────────────────────

Requirements Phase:

  - Draft             → Backlog

  - In Review         → Backlog

  - Approved          → To Do



Development Phase:

  - In Development    → In Progress



Validation Phase:

  - In Testing        → Testing

  - In QA             → Testing



Completed Phase:

  - Completed         → Done

  - Released          → Done

This approach groups multiple Catalio statuses into broader Jira statuses, reducing complexity.

Strategy 3: Milestone-Based Mapping

For teams tracking requirements through major milestones:

Catalio Status         → Jira Status

────────────────────────────────────────

Pre-Development:

  - Draft              → Backlog

  - Refined            → Refined



Sprint Ready:

  - Approved           → Ready for Dev



Active Development:

  - In Development     → In Progress

  - In Review          → In Review



Quality Assurance:

  - In QA              → In QA

  - In UAT             → User Testing



Delivery:

  - Released           → Closed

  - Deployed           → Closed

Handling Workflow Transitions

Valid Transition Checking

Jira workflows often restrict which status transitions are allowed. The integration handles this intelligently:

Automatic Path Finding:

If direct transition isn’t allowed, Catalio finds a valid path:

Example:

  Desired: Backlog → Testing (not allowed directly)



  Valid Path Found:

    Backlog → To Do → In Progress → Testing



  Result:

    Catalio triggers three transitions in sequence

Manual Review Queue:

For workflows requiring human approval:

Scenario:

  Catalio: Approved → In Development

  Jira: To Do → (requires approval) → In Progress



Result:

  - Issue moves to approval queue in Jira

  - Catalio status marked as "Pending Sync"

  - After Jira approval completes, Catalio syncs to final status

Status Sync Direction

Configure sync direction per status or globally:

Recommendation: Split Authority

Status Authority by Phase:

  Requirements Phase → Catalio Authoritative:

    - Draft, In Review, Approved

    - Reason: Business analysts manage requirements

    - Direction: Catalio → Jira (one-way)



  Development Phase → Bi-Directional:

    - In Development, In Testing

    - Reason: Both teams need visibility

    - Direction: Catalio ↔ Jira



  Delivery Phase → Jira Authoritative:

    - Released, Deployed

    - Reason: DevOps manages releases in Jira

    - Direction: Jira → Catalio (one-way)

Resolution and Status Closure

Handling Jira Resolutions

Jira’s resolution field provides additional context when closing issues:

Jira Resolution      → Catalio Status + Metadata

───────────────────────────────────────────────

Done                → Completed

                      resolution_type: "Implemented"



Won't Fix           → Rejected

                      resolution_type: "Declined"



Duplicate           → Completed

                      resolution_type: "Duplicate"

                      Note: Link to duplicate requirement



Cannot Reproduce    → Completed

                      resolution_type: "Invalid"



Works as Intended   → Completed

                      resolution_type: "Working"

Configuration:

  1. Settings → Jira Integration → Resolution Mapping
  2. Map each Jira resolution to Catalio status + metadata
  3. Optionally create Catalio comment with resolution reason

Reopening Requirements

When Jira issues reopen, sync the change:

Jira Reopen         → Catalio Action ──────────────────────────────────── Reopen from Done    →

Revert to "In Development" Create audit trail comment



Reopen from Testing → Revert to "In Development" Flag for technical review

Configure reopen behavior in Status Mapping → Reopen Rules.

Status Sync Timing

Real-Time vs Batched Sync

Real-Time Sync (via Webhooks):

  • Immediate updates (< 30 seconds)
  • Requires webhook configuration
  • Best for active development

Batched Sync (Scheduled):

  • Runs every 15 minutes (configurable)
  • More efficient for high-volume projects
  • Provides batch conflict resolution

Hybrid Approach (Recommended):

Configuration:

  Real-time for: In Progress, Testing, Done

  Batched for: Backlog, To Do



Reason: Active statuses need immediate visibility Early statuses can tolerate slight delays

Status Dashboard

Monitor status synchronization health:

  1. Integration Dashboard → Status Sync
  2. View metrics:
    • Successful syncs (last 24 hours)
    • Failed transitions with reasons
    • Pending approvals in workflow
    • Status drift (mismatched between systems)
  3. Export reports for process optimization

Sprint Planning

Integrating Catalio Requirements into Sprints

The Jira integration enables seamless sprint planning using Catalio requirements as the foundation for development work.

Sprint Planning Workflow

Phase 1: Requirement Prioritization (Catalio)

Before Sprint Planning:

  1. Product Owner reviews and prioritizes requirements in Catalio
  2. Requirements marked as “Ready for Development” sync to Jira backlog
  3. Catalio’s AI insights help identify dependencies and risks
  4. Acceptance criteria and context are complete

Example:

Catalio Requirement: "Multi-factor Authentication" Priority: High Status: Ready for Development

Story Points: (to be estimated) Dependencies: "User Authentication Service" (completed) Acceptance

Criteria: - SMS-based verification - TOTP app support - Backup codes generation

This requirement automatically appears in the Jira project backlog.

Phase 2: Sprint Planning Meeting (Jira)

During Sprint Planning:

  1. Development Team reviews synced requirements in Jira backlog
  2. Team estimates story points directly in Jira
  3. Requirements are committed to sprint using Jira’s sprint management
  4. Technical tasks and sub-tasks are created as needed

Jira Actions:

1. Drag "Multi-factor Authentication" story into Sprint 15

2. Estimate story points: 8

3. Create sub-tasks:

   - "Implement SMS provider integration" (3 points)

   - "Build TOTP verification flow" (3 points)

   - "Create backup codes UI" (2 points)

4. Assign sub-tasks to developers

Phase 3: Sprint Execution (Bi-directional Sync)

During Sprint:

  • Jira story/sub-task status updates sync to Catalio
  • Development team works in Jira (their tool of choice)
  • Product owner monitors progress in Catalio dashboard
  • Sprint assignment reflects in Catalio for reporting

Catalio View:

Requirement: "Multi-factor Authentication"

  Status: In Development

  Sprint: Sprint 15 (Jira)

  Progress: 2 of 3 sub-tasks completed

  Estimated Completion: 3 days remaining

Phase 4: Sprint Review (Catalio Insights)

At Sprint End:

  • Catalio aggregates completed requirements
  • AI-generated sprint retrospective insights
  • Traceability report: requirement → implementation → testing
  • Velocity metrics for future planning

Sprint Sync Configuration

Enable Sprint Synchronization

  1. Project Settings → Jira Integration → Sprint Features
  2. Enable “Sync Sprint Assignment”
  3. Configure sync preferences:
Sprint Sync Options:

  Sync Sprint Assignment: Yes - When Jira issue added to sprint, update Catalio requirement



  Sync Sprint Metadata: Yes - Sprint name, dates, goals visible in Catalio



  Create Catalio Sprint View: Yes - Mirror Jira sprint structure in Catalio



  Bi-directional Sprint Changes:

    No (Recommended) - Only Jira manages sprint assignment - Prevents accidental sprint changes from

    Catalio

Sprint Field Mapping

Map sprint information to Catalio fields:

Field Mappings:



  Jira Sprint Name → Catalio "Sprint" (Text field)

    Example: "Sprint 15" → requirement.sprint = "Sprint 15"



  Jira Sprint Start → Catalio "Sprint Start Date" (Date)



  Jira Sprint End → Catalio "Sprint End Date" (Date)



  Jira Sprint Goal → Catalio Comment

    Format: "Sprint Goal: {goal_text}"

Sprint Backlog Refinement

Refining Requirements Before Sprint

Backlog Refinement Workflow:

  1. Product Owner marks requirement as “Needs Refinement” in Catalio
  2. Syncs to Jira with label “needs-refinement”
  3. Team discusses in refinement meeting
  4. Acceptance criteria updated in Jira
  5. Smart merge brings updates back to Catalio
  6. Status changes to “Ready for Sprint”

Example:

Week 1: PO creates requirement in Catalio

  Status: Draft



Week 2: Requirement refined

  Status: In Review → Syncs to Jira with "needs-refinement" label



Week 3: Refinement meeting in Jira

  Acceptance criteria clarified

  Technical approach discussed

  Story points estimated (5 points)

  Label changed to "refined"



Week 4: Sprint planning

  Status: Approved → Ready for Sprint

  Added to Sprint 16

Handling Unfinished Sprint Work

When sprint ends with incomplete work:

Jira Action:

  • Issues not completed remain in backlog or move to next sprint

Catalio Sync:

Incomplete Requirement Handling:



  If Jira issue moved to next sprint:

    → Update Catalio requirement sprint assignment

    → Add comment: "Carried over from Sprint 15 to Sprint 16"

    → Retain status: "In Development"



  If Jira issue returned to backlog:

    → Clear sprint assignment in Catalio

    → Status: "Ready for Development"

    → Add comment: "Returned to backlog from Sprint 15"

Sprint Reporting

Sprint Progress in Catalio

View sprint progress from the requirements perspective:

Dashboard Widgets:

  1. Sprint Burndown:

    • Requirements completed vs remaining
    • Story points completed (synced from Jira)
    • Projected completion date

  2. Sprint Velocity:

    • Historical requirement completion rate
    • Story points delivered per sprint
    • Trend analysis for capacity planning

  3. Requirement Flow:

    • Time from “Approved” to “In Development”
    • Time from “In Development” to “Done”
    • Bottleneck identification

Example Report:

Sprint 15 Summary:

  Committed: 12 requirements (48 story points)

  Completed: 10 requirements (42 story points)

  Carry-over: 2 requirements (6 story points)



  Velocity: 42 points (target: 40)



  Requirements by Status:

    ✓ Done: 10

    → In Progress: 2

    ○ To Do: 0

Cross-Sprint Traceability

Track requirement journey across multiple sprints:

Requirement: "Advanced Reporting Dashboard"

  Created: 2025-01-15 (Catalio)

  Approved: 2025-01-20

  Synced to Jira: 2025-01-20

  Sprint 13: Not completed (complexity underestimated)

  Sprint 14: Continued work

  Sprint 15: Completed 2025-02-10



  Total Time: 26 days from approval to completion

  Sprints: 3 (across 6 weeks)

Access in Requirement History → Sprint Timeline.

Traceability

End-to-End Requirement Tracking

The Catalio-Jira integration provides complete traceability from initial requirement through deployment, enabling compliance, impact analysis, and process optimization.

Traceability Architecture

Bidirectional Linking

Every synced requirement maintains bidirectional links:

Catalio → Jira:

Requirement Record:

  ID: REQ-1234

  Title: "Multi-factor Authentication"

  Jira Link:

    Project: PROD

    Issue Key: PROD-567

    Issue ID: 10234

    Issue URL: https://yourcompany.atlassian.net/browse/PROD-567

    Sync Status: Active

    Last Synced: 2025-01-14 10:23:45 UTC

Jira → Catalio:

Jira Issue PROD-567:

  Custom Field: "Catalio Requirement"

    Value: REQ-1234

    URL: https://catalio.yourcompany.com/requirements/REQ-1234



  Link Type: "Traced from"

  Description: "[View in Catalio](catalio-link)"

Traceability Matrix

Catalio generates comprehensive traceability matrices:

Requirement ID | Requirement Title           | Jira Issue | Status       | Sprint  | Commits | Tests | Deploy

─────────────────────────────────────────────────────────────────────────────────────────────────────────────

REQ-1234      | Multi-factor Authentication | PROD-567   | Completed    | Sprint 15 | 12    | 8    | v2.3.0

REQ-1235      | User Profile Export         | PROD-568   | In Progress  | Sprint 16 | 5     | 2    | -

REQ-1236      | API Rate Limiting           | PROD-569   | Testing      | Sprint 16 | 8     | 6    | -

Access: Reports → Traceability Matrix

Development Progress Tracking

Code Commit Integration

When development teams link commits to Jira issues, Catalio tracks implementation progress:

Setup:

  1. Enable “Track Development Activity” in integration settings

  2. Developers include Jira issue key in commit messages:

    git commit -m "PROD-567: Add TOTP verification endpoint"



3. Jira's development panel captures commits

4. Catalio syncs commit metadata



**Catalio Display:**

Requirement: “Multi-factor Authentication” Development Activity: Commits: 12 Authors: 3 (Alice, Bob, Charlie) Lines Changed: +847, -123 Last Commit: 2025-01-13 14:22:00 Branches: feature/mfa, feature/backup-codes

Recent Commits: - “Add SMS provider integration” - Alice - 2 days ago - “Implement TOTP token validation” - Bob - 1 day ago - “Create backup codes UI component” - Charlie - 4 hours ago



#### Pull Request Tracking



Monitor code review progress:

Requirement: “Multi-factor Authentication” Pull Requests: PR #234: “Implement MFA backend” (Merged) Status: ✓ Merged Reviews: 2 approvals Merged: 2025-01-12

PR #241: "MFA frontend components" (Open)

  Status: → In Review

  Reviews: 1 approval, 1 requested changes

  Updated: 2 hours ago



### Testing and Quality Assurance



#### Test Coverage Tracking



Link test execution results to requirements:



**Integration Flow:**



1. Jira issue includes acceptance criteria

2. Test cases created in test management tool (Zephyr, Xray)

3. Test results sync to Jira via test tool integration

4. Catalio displays aggregated test status



**Catalio Test View:**

Requirement: “Multi-factor Authentication” Test Coverage: Total Tests: 8 Passed: 6 ✓ Failed: 1 ✗ Blocked: 1 ⊘

Test Details: ✓ TC-101: SMS verification success flow ✓ TC-102: TOTP token validation ✗ TC-103: Invalid phone number handling ⊘ TC-104: Backup codes (blocked by PROD-599) ✓ TC-105: MFA enrollment UI ✓ TC-106: MFA settings page ✓ TC-107: Remember device feature ✓ TC-108: MFA disable flow



#### Quality Gate Validation



Define quality gates that must pass before requirement is considered complete:

Quality Gates for “Completed” Status:

  1. All Acceptance Criteria Met: Required Status: 3/3 criteria ✓

  2. Code Review Approved: Required Status: 2 approvals ✓

  3. Test Coverage ≥80%: Required Status: 87% coverage ✓

  4. No Critical Bugs: Required Status: 0 critical bugs ✓

  5. Security Scan Passed: Required Status: No vulnerabilities ✓

  6. Documentation Updated: Required Status: API docs updated ✓

Result: All gates passed → Auto-transition to Completed



Configure gates: **Project Settings** → **Quality Gates**



### Deployment Tracking



#### Release Association



Track which requirements deployed in which releases:



**Jira Fix Version:**

Jira Issue PROD-567: Fix Version/s: v2.3.0

Catalio Syncs: Requirement REQ-1234 Released In: v2.3.0 Release Date: 2025-01-15 Deployment: Production

Release Notes Generation:

Catalio auto-generates release notes from completed requirements:

# Release v2.3.0 - January 15, 2025



## New Features



- **Multi-factor Authentication** (REQ-1234, PROD-567) Enhanced security with SMS and TOTP support



- **User Profile Export** (REQ-1235, PROD-568) Users can download their profile data in JSON format



## Improvements



- **Performance Optimization** (REQ-1240, PROD-575) Reduced API response time by 40%



## Bug Fixes



- Fixed session timeout issue (REQ-1238, PROD-572)

Access: Releases → v2.3.0 → Generate Release Notes

Deployment Environment Tracking

For teams with multiple environments:

Requirement: "Multi-factor Authentication"

  Deployment Status:



    Development:

      Deployed: 2025-01-12

      Version: feature/mfa-branch

      Status: ✓ Passing



    Staging:

      Deployed: 2025-01-13

      Version: v2.3.0-rc1

      Status: ✓ Passing



    Production:

      Deployed: 2025-01-15

      Version: v2.3.0

      Status: ✓ Healthy

Compliance and Audit Trail

Regulatory Traceability

For regulated industries (healthcare, finance, aerospace):

Complete Audit Trail:

Requirement REQ-1234: "Multi-factor Authentication"



  Lifecycle Events:

    2025-01-05 10:15:23 | Created | User: sarah@company.com

    2025-01-06 14:22:11 | Description Updated | User: sarah@company.com

    2025-01-07 09:30:45 | Status: Draft → In Review | User: sarah@company.com

    2025-01-08 11:05:33 | Approved | User: john.manager@company.com

    2025-01-08 11:15:22 | Synced to Jira | System: Catalio Integration

    2025-01-08 11:15:45 | Jira Issue Created | PROD-567

    2025-01-11 09:00:00 | Status: In Development | User: bob.dev@company.com

    2025-01-13 14:45:32 | PR #234 Merged | System: GitHub Integration

    2025-01-14 10:30:15 | Status: In Testing | User: jane.qa@company.com

    2025-01-14 15:45:00 | All Tests Passed | System: Test Integration

    2025-01-15 08:00:00 | Status: Completed | User: alice.dev@company.com



  Change History:

    All 15 changes documented with before/after values



  Approvals:

    Business Approval: john.manager@company.com (2025-01-08)

    Technical Review: alice.dev@company.com (2025-01-10)

    QA Sign-off: jane.qa@company.com (2025-01-14)

    Security Review: security@company.com (2025-01-14)

Export audit trail: Requirement Details → Actions → Export Audit Trail (PDF/CSV)

Impact Analysis

When requirements change, analyze downstream impact:

Change Impact Report:

Requirement REQ-1234: Description Changed



  Impacted Items:

    Jira Issues:

      - PROD-567 (parent story)

      - PROD-570 (sub-task)

      - PROD-571 (sub-task)



    Related Requirements:

      - REQ-1235 (depends on this)

      - REQ-1240 (related)



    Test Cases:

      - TC-103 (may need update)

      - TC-104 (may need update)



    Documentation:

      - API Docs: "Authentication API"

      - User Guide: "Security Settings"



  Recommendation: Review and update impacted items

Trigger: Requirement Details → Actions → Analyze Impact

Reporting and Analytics

Requirement Velocity

Measure how quickly requirements move through the pipeline:

Average Time in Stage (Last 3 Months):



  Draft → Approved: 3.5 days

  Approved → In Development: 2.1 days

  In Development → In Testing: 8.3 days ⚠️

  In Testing → Completed: 2.7 days



  Total: Approval to Completion: 16.6 days



Insights:

  ⚠️ Development phase is bottleneck (50% of total time)

  ✓ Testing phase is efficient

  → Recommend: Increase developer capacity or reduce scope

Requirement Success Metrics

Sprint 15 Outcomes:



  Committed Requirements: 12

  Completed: 10 (83%)

  Carried Over: 2 (17%)



  On-Time Delivery: 75% (9 of 12 met deadline)

  Quality:

    First-time Pass Rate: 80%

    Defects Found: 3 (0.3 per requirement)



  Customer Satisfaction:

    Requirements Accepted: 10/10 (100%)

    Change Requests: 1 (minor)

Access: Reports → Sprint Retrospective → Sprint 15

Best Practices

Agile Workflow Optimization

1. Single Source of Truth per Phase

Designate authority for each development phase:

Phase Authority Model:

  Requirements Phase (Catalio):

    - Requirement creation and refinement

    - Acceptance criteria definition

    - Business prioritization

    - Stakeholder approval



  Planning Phase (Shared):

    - Estimation (Jira)

    - Sprint assignment (Jira)

    - Priority validation (Catalio)



  Development Phase (Jira):

    - Task breakdown

    - Status updates

    - Technical decisions

    - Code reviews



  Reporting Phase (Catalio):

    - Progress tracking

    - Stakeholder communication

    - Impact analysis

    - Release planning

Benefit: Reduces conflicts and clarifies team responsibilities

2. Consistent Naming Conventions

Maintain clarity across systems:

Requirement Naming:

Format: [Category] Action - Object



Examples:

  ✓ [Auth] Add - Multi-factor Authentication

  ✓ [API] Implement - Rate Limiting

  ✓ [UI] Redesign - User Dashboard



Not:

  ✗ MFA feature

  ✗ New authentication

  ✗ Update user stuff

Jira Issue Summary:

Inherit from Catalio requirement title



Catalio: "[Auth] Add - Multi-factor Authentication"

Jira:    "[Auth] Add - Multi-factor Authentication"

         (identical for easy cross-reference)

3. Leverage Labels and Tags

Use consistent labeling for filtering and reporting:

Shared Labels:

Priority Labels:

  - critical-priority

  - high-priority

  - medium-priority

  - low-priority



Type Labels:

  - feature

  - enhancement

  - bugfix

  - technical-debt



Theme Labels:

  - user-experience

  - security

  - performance

  - compliance

Configure label sync: Settings → Jira Integration → Label Mapping

4. Optimize Sync Frequency

Balance real-time needs with system performance:

Recommended Configuration:

Real-time Sync (via Webhooks):

  Enabled for:

    - Status changes

    - Sprint assignments

    - Priority changes

  Response Time: < 30 seconds



Batched Sync (Scheduled):

  Frequency: Every 15 minutes

  Syncs:

    - Description updates

    - Comments

    - Custom fields

    - Label changes



Manual Sync:

  Available for: Individual requirements or entire projects

  Use Case: Testing, troubleshooting, bulk updates

Why? Real-time sync for critical changes keeps teams informed immediately, while less urgent updates batch efficiently.

5. Define Clear Acceptance Criteria

Write testable acceptance criteria in Catalio that translate well to Jira:

Format:

Catalio Acceptance Criteria:



## Functional Criteria



- [ ] User can enable MFA from security settings page

- [ ] System sends SMS verification code within 30 seconds

- [ ] User can verify code with 6-digit input

- [ ] System locks account after 3 failed attempts



## Non-Functional Criteria



- [ ] SMS delivery success rate ≥ 99%

- [ ] MFA verification response time < 200ms

- [ ] Support 10,000 concurrent MFA verifications



## Security Criteria



- [ ] Codes expire after 10 minutes

- [ ] Codes are single-use only

- [ ] Failed attempts logged for audit

Syncs to Jira with checkboxes preserved, enabling developers to track completion.

Team Collaboration Patterns

Product Owner Workflow

Daily Routine:

  1. Morning: Review new requirements in Catalio

    • AI identifies unclear requirements
    • Refine descriptions and acceptance criteria
    • Mark ready requirements for sync

  2. Sprint Planning: Prioritize synced requirements in Jira

    • Participate in estimation
    • Clarify questions from dev team
    • Approve sprint commitment

  3. During Sprint: Monitor progress in Catalio dashboard

    • View real-time status updates from Jira
    • Respond to questions in Catalio comments (sync to Jira)
    • Adjust priorities as needed

  4. Sprint Review: Validate completed requirements

    • Review traceability reports
    • Accept or reject based on acceptance criteria
    • Plan next sprint priorities

Development Team Workflow

Daily Routine:

  1. Morning Standup: Review sprint board in Jira

    • Update task statuses
    • Flag blockers (auto-syncs to Catalio for PO visibility)

  2. Development: Work entirely in Jira

    • Update story progress
    • Create sub-tasks as needed
    • Link commits and PRs

  3. No Catalio Login Required:

    • All necessary context synced to Jira descriptions
    • Acceptance criteria visible in Jira
    • Changes flow back to Catalio automatically

QA Team Workflow

Testing Process:

  1. Test Planning: Requirements with acceptance criteria sync to Jira
  2. Test Execution: Update Jira issue status to “In Testing”
    • Status syncs to Catalio for stakeholder visibility
  3. Defect Reporting: Create bugs linked to Jira stories
    • Bugs automatically link to parent requirement in Catalio
  4. Sign-off: Move to “Done” in Jira
    • Catalio requirement status updates to “Completed”

Data Hygiene and Maintenance

Regular Cleanup Tasks

Weekly:

  • Review sync errors and resolve conflicts
  • Archive completed requirements (past sprint)
  • Validate custom field mappings still accurate

Monthly:

  • Audit orphaned issues (Jira issues without Catalio requirements)
  • Review and optimize status mappings
  • Update integration credentials if needed
  • Generate traceability report for stakeholders

Quarterly:

  • Comprehensive integration health check
  • Review and update custom field mappings
  • Optimize sync performance based on usage patterns
  • Train new team members on integration workflows

Handling Edge Cases

Scenario: Jira Issue Created Manually

When developers create Jira issues outside the sync:

Options:

  1. Link to Existing Requirement:

    - Use "Link to Catalio" button in Jira

    - Select matching requirement

    - Enable bi-directional sync



  2. Create Catalio Requirement from Jira:

    - Use "Import to Catalio" action

    - Generates requirement from Jira issue

    - Establishes sync relationship



  3. Leave Unlinked:

    - For technical tasks not tied to business requirements

    - Track separately in Jira

Scenario: Bulk Requirement Changes

When making large-scale changes:

Best Practice:

  1. Temporarily Pause Real-time Sync: Settings → Pause Webhooks



  2. Make Bulk Changes in Catalio:

    - Update multiple requirements

    - Modify mappings or custom fields



  3. Trigger Manual Sync: Actions → Bulk Sync to Jira



  4. Resume Real-time Sync: Settings → Resume Webhooks



Benefit: Prevents sync conflicts and improves performance

Security and Compliance

Access Control

Principle of Least Privilege:

Jira Service Account Permissions:

  Required:

    - Browse Projects

    - Create Issues

    - Edit Issues



  Optional (based on features):

    - Manage Sprints (if sprint sync enabled)

    - Delete Issues (if cascade delete enabled)



  NOT Required:

    - Administer Jira

    - Administer Projects

    - Manage Webhooks (set up manually by admin)

Catalio User Permissions:

Role-Based Access:

  Viewer:

    - View synced requirements

    - View Jira links

    - No sync actions



  Contributor:

    - Create and edit requirements

    - Trigger manual sync

    - View sync status



  Admin:

    - Configure integration settings

    - Manage field mappings

    - Resolve sync conflicts

    - Access audit logs

Data Security

In Transit:

  • All communication uses HTTPS/TLS 1.2+
  • API tokens encrypted in transit
  • OAuth tokens use secure authorization flows

At Rest:

  • API tokens encrypted with AES-256
  • Sync logs retention: 90 days (configurable)
  • PII handling complies with GDPR/CCPA

Audit Trail:

  • All integration actions logged
  • User attribution for manual syncs
  • Export audit logs for compliance reviews

Performance Optimization

Scaling for Large Teams

For projects with 1000+ requirements:

Optimization Configuration:

  Sync Strategy:

    - Use batched sync (every 30 minutes)

    - Enable webhook filtering (sync only specific statuses)

    - Implement incremental sync (only changed items)



  Field Mapping:

    - Minimize custom field mappings (only essential fields)

    - Disable description smart merge for large text fields

    - Use direct mappings over transformations



  Jira Query Optimization:

    - Add JQL filters to limit synced issues

    - Example: 'project = PROD AND status != Closed'



  Database:

    - Archive old sync records (> 6 months)

    - Index frequently queried fields

Expected Performance:

  • 1000 requirements: < 5 minutes for full sync
  • 10,000 requirements: < 30 minutes for full sync

Monitoring Integration Health

Key Metrics Dashboard:

Integration Health Score: 98% ✓



Sync Performance:

  Real-time Sync Latency: 12 seconds (avg)

  Batched Sync Duration: 3 minutes

  Failed Syncs (24h): 2 (0.1%)



Data Consistency:

  Requirements in Sync: 487 / 492 (99%)

  Orphaned Issues: 3

  Pending Conflicts: 1



System Health:

  API Rate Limit: 15% used

  Webhook Delivery: 99.8% success

  Last Full Sync: 15 minutes ago

Access: Integration Dashboard → Health Metrics

Troubleshooting

Common Issues and Solutions

Issue: “Authentication Failed”

  • Verify API token/credentials haven’t expired
  • Check Jira user account is active
  • Confirm network connectivity to Jira instance

Issue: “Invalid Status Transition”

  • Review Jira workflow allows the transition
  • Update status mapping to use valid path
  • Check user permissions for workflow transitions

Issue: “Custom Field Not Syncing”

  • Verify field mapping configuration
  • Ensure Jira custom field ID is correct
  • Check field type compatibility

Issue: “Sync Delays > 5 Minutes”

  • Verify webhooks are configured correctly
  • Check fallback scheduled sync is running
  • Review system load and performance metrics

Support Resources

Next Steps

Now that you understand Jira integration, explore these related topics:

Ready to connect Catalio to Jira? Navigate to Settings → Integrations → Jira to begin setup.
Next
GitHub Integration