Configuring Jama Connect® to prepare for a Jira Integration

Author: Patrick Garman

Updated: January 2025

Audience: Jama Connect® Organization Admins

Products Applicable: Jama Connect®, Jama Connect Interchange™

Use Case

Configure Jama Connect® to prepare for a Jira Integration

Best Practice

Integrating Jama Connect® and Atlassian Jira extends your project traceability beyond requirements decomposition and V&V activities to include development tasks and completion status. The integration also allows your teams to work in the tool best suited for their purpose without creating information silos or missed communication between teams.

Implementation

Consider this sample workflow:

1. Requirements are authored, refined, and approved in Jama Connect®.
2. When a set of related requirements is ready to initiate development, requires additional research, or any other task to be assigned, a backlog item is created and related downstream from these requirements in the Jama Connect® Project.
3. Jama Connect Interchange™ recognizes the new backlog item and creates a synced issue in the indicated Jira project.
4. In Jira, discipline leads or product owners decompose these backlog issues as needed into stories or tasks to be completed.
5. Test Cases are authored in Jama Connect® to verify that the backlog items or tasks meet the acceptance criteria defined in the requirements.
6. When executing these test cases in Jama Connect®, any defects are logged.
7. Jama Connect Interchange™ recognizes that new defects have been logged and creates synced defects or issues in the indicated Jira project for triage and research.
8. As root causes for defects are identified, Change Requests are created in Jama Connect® to track which requirements must be updated or what new requirements must be authored to resolve the defect.
9. A new backlog item is created in Jama Connect® to initiate the implementation of these fixes, and the cycle repeats itself.

In the example above, the backlog item could represent several items in your Jama Connect® configuration. For software development, typical backlog items include Epics, Capabilities, Features, and User Stories. You can create a Research Spike item type if additional information is needed to validate a requirement or identify alternative options. The backlog item could also be assigned as a Task. The backlog item(s) created in Jama Connect® essentially represents any work needed to refine or implement your requirements.

With this integration workflow-enabled, Jama Connect® is the source of truth for requirements approval and traceability. It receives updates on implementation completeness for visibility and reporting.

Configuring Jama Connect® in preparation for integrating with Jira. 

There are several steps to updating your Jama Connect® configuration to prepare for integration into Jira projects.

1. Identify the types of backlog items you want to include in your traceability. 
   • The goal should not be to replicate every issue type you track in Jira – only to the level of granularity that you need for reporting in Jama Connect.
   • Everyday backlog items are EPICS, STORIES, and TASKS.
2. Identify what fields or metadata you want to sync for each backlot item type between Jama Connect® and Jira.  Recommended fields include:
   • Name (required)
   • Description (required)
   • Development Stage
     • This will reflect the Kanban or other status of the synced issue in Jira.
   • Approval Status
     • This is a picklist field in Jama Connect that indicates the approval status of the backlog issue—it is separate from the Kanban or completion status controlled in Jira.
   • Jira URL
     • When Jama Connect Interchange creates the synced issue in Jira, it can write the URL for it in this field, allowing Jama Connect users to open it quickly when viewing the Jama Connect item.
3. Create new or modify existing backlog item types in Jama Connect®.
4. Make the backlog item types visible in Jama Connect® projects you want to include in integrations.
5. Update project relationship rules to include the allowable relationships between requirements and backlog items.
6. Update the Explorer Tree in your template projects and any projects included in integration to include containers for your backlog item types.

Sample item type configurations for backlog items

Epic

Item Type details and enabled widgets:

Recommended Epic fields:

Note that Project ID, Global ID, Name, and Description fields are required for all item types in Jama Connect.  You can edit these fields to change the display label in the Jama Connect UI, but you cannot delete them.

Configure fields that will be controlled in Jira, like Development Stage and Issue Link, Read Only with Allow API Overwrite enabled.  That will allow Jama Connect Interchange to update these fields in Jama Connect as they are updated in Jira and will prevent Jama Connect users from accidentally overwriting this data:

For more straightforward integration configuration and administration, create fields that will be controlled in Jira, such as Text Fields or Text Box fields in Jama Connect.  This way, you do not have to configure pick lists or match users between tools.  You can also create these fields as pick list or multi-select fields and match the values in Jira, but be aware that if the picklist values are updated in Jira, you will need to update the matching picklist values in both Jama Connect and your integration mapping.

Task

Item Type details and enabled widgets:

Recommended Task fields:

Sample Relationship Rule Set

To provide guardrails around which requirement types can be related to a backlog item in your Jama Connect projects, could you include the backlog item types you create in your relationship rule set?

In this example, Backlog Items can be related downstream from Subsystem Requirements and upstream from Test Cases but cannot be related directly to any other item type in this project.  In your relationship rule set, you would substitute “Backlog Item” for any item types you created for the integration (e.g., Epic or Task).

Notice that the line connecting Subsystem Requirements to Backlog Items is dotted, indicating that not all Subsystem Requirements are expected to have a related Backlog Item.  The relationship link between the Backlog Items and Test Cases is solid (For Coverage = Yes), which indicates that each Backlog Item is expected to have at least one downstream-related Test Case, and each Test Case is expected to have at least one Backlog Item related upstream.  With this configuration, Jama Connect will mark any Backlog Item missing a Test Case as “Missing Coverage” and any Test Case not associated with a Backlog Item as “Orphaned.”

Suppose you want your project members to relate a backlog item to any item type in your project. In that case, you can leave the backlog item type out of your relationship rule set and enable the “Allow any item type not mentioned in this rule set to be related to any item type, including those in the rule set” option:

Project Explorer Tree Sample

In this example, a Component contains all of my project backlog item types—in this case, Epics, Tasks, and related Test Cases.

I have configured the default view in the Project Explorer Tree to Show Relationships in the Tree.  With this setting enabled, I can expand a requirement to view its related Epics and Tasks for more straightforward traceability navigation.

Additional Resources

• Backlog Item:  any item type intended to track the completeness of a task related to requirements.
• Setup Jira Integration using Jama Connect Interchange™
• Jama Connect® Integrations and Support
• Troubleshooting Common Integration Issues
• Best Practices for Creating and Configuring a New Item Type

Please feel free to leave feedback in the comments below.