Jira and Jira Align Integration: Defect or Story of Type Defect? What's the difference?

Peter Jessen
Rising Star
Rising Star
Rising Stars are recognized for providing high-quality answers to other users. Rising Stars receive a certificate of achievement and are on the path to becoming Community Leaders.
January 7, 2020

In his excellent article "Jira and Jira Align Integration: Issue, Story, and Epic Management" my buddy @Tim Keyes provides a nice overview of the basics of integrating Jira stories and epics with Jira Align.

One area that, in my opinion, deserves additional discussion is how to integrate Jira defects with Jira Align.

First of all, some discussion is probably merited on a bug vs a defect, why we should care, and when to use or not use either type. Many organizations, due to such factors as distributed teams or silos between dev and QA, use Jira Bugs to track tests that failed during the normal development cycle prior to Product Owner (PO) acceptance of the completed story. They also use the same Jira Bug issue type to track defects that emerge after PO acceptance during integration testing or after deployment to production.

This is a case of mixing apples and oranges - two different artifact types, of of which needs to be tracked in QA metrics (post-PO acceptance defects) and one that shouldn't (pre-PO acceptance bugs). Why track post-PO acceptance defects but not pre-PO acceptance bugs? Because the defects are new work that needs to be pointed and prioritized like any other work; the bugs are already accounted for in the pointing and prioritization of the original story under which they are spawned during development.

Example: During development a 3-point story leads to QA logging five 1 point bugs (prior to PO acceptance) during testing. In this case, our metrics would show 6 issues worked by the team for a total of 8 points, when in fact only one 3-point story was actually developed. The five 1-point bugs inflate both the team velocity and issue count metrics, as they were accounted for in the team's original 3 point estimate for the story. (NOTE: The smallest meaningful work is 1 point, not fractional points. Yes, I know others argue for 0.5 point stories.) Any true defects in the original story that need correcting would only be determined during PO acceptance, when the PO might accept a story with a defect that needs fixing later. That defect would then be added to the team backlog and pointed/prioritized like any other story.

Now back to Jira Align and how to integrate true defects. If an organization is using Jira to track normal development testing generated bugs, then the Jira Bug type would be used for those and NOT integrated with Jira Align. Create a separate Jira Defect issue type to integrate with Jira Align. If your organization is properly using the Jira Bug issue type for true defects (as described above) then you have two options for integrating them with Jira Align, as follows:


The default behavior for mapping Jira defects to Jira Align causes the Jira defects to be accumulated in the Defects area of the Team level. This is effectively a triage area for the defects to be assessed prior to being converted to stories to be worked by an agile team. As they come over to Jira Align, when configured this way, the defects are stripped of their epic link, team, story point estimate, and other data.

While this approach makes sense from a pure agile perspective, it is not the behavior most organizations expect or desire when integrating with Jira. In four years implementing AgileCraft/Jira Align with Jira I've implemented defects this way once.

When to chose this option: The organization that chose this method had minimal production defects due to proven high quality code coming out of their agile teams. If your organization has minimal production defects that don't impact team velocity, then this is the option to chose, as your agile discipline will probably include triaging defects before working them.

To integrate Jira with Jira Align for this configuration do the following:

  1. Navigate to Administration -> Jira Settings -> Jira Setup tab
  2. Scroll down to Issue Types
  3. Next to Issue Type Defect enter the Jira Issue ID and Name.
  4. Scroll to the bottom of the section and click Save.


The preferred way, in my experience, most organizations chose to implement defect tracking in Jira Align, once they understand the behaviors of the two options, is to map defects as Stories of Type Defect. This option maintains the epic link, the story points, the team, and the other data that is stripped from the defect in the default behavior.

This option provides such benefits as:

  • Visibility of the defects on the Program Board under their respective features (Jira Epics)
  • Defects are properly included in team sprint velocity, as well as program level velocity
  • ARTs/programs can determine what percentage of their overall velocity needs to be reserved for emergent production defects.
    • NOTE: In one organization with monolithic legacy code, 40% of each sprint's velocity was reserved for EMERGENT production defects.
  • Teams familiar with Jira will be more comfortable with this approach.

When to chose this option: The majority or organizations that have been using Jira for years or who have high volumes of production defects will want to use this approach for a variety of reasons. I personally believe this should become the default behavior when integrating Jira and Jira Align.

To integrate Jira with Jira Align for this configuration do the following:

  1. Navigate to Administration -> Jira Settings -> Custom Issue tab
  2. Click the Add button to add a new row to the list.
  3. Enter the name of the issue type used in Jira (ex: Bug or Defect) in the Issue Type column
  4. Select Defect from the Story Type drop-down list
    • NOTE: This list can be edited under Administration -> Platform -> Dropdowns tab -> Story Types
  5. The Connector column will default to Jira, unless you have multiple connectors.
  6. Click the blue Save button.


Adding this because of @jenny.bellas observation in the comments.

The biggest trade-off between using the default defect mapping in Align vs using mapping defects as stories of type defect is the loss of the rich quality reporting available in Align. Please see my answer in the comments below to @jenny.bellas question/observation.

What are your thoughts? How have you integrated defects from Jira to Jira Align?


PS: Of course, after I finished writing this, I discovered @Tim Keyes had already published a related article! Oh well. Here's Tim's article, for completeness.


Tim Keyes
Atlassian Team
Atlassian Team members are employees working across the company in a wide variety of roles.
January 7, 2020

Hey Peter,


Great Post!  I have seen this discussion play out for numerous customers over the past two years.  You presented both cases more eloquently than I would have!




Like Andy - PTC Redundant likes this
Andy - PTC Redundant
Rising Star
Rising Star
Rising Stars are recognized for providing high-quality answers to other users. Rising Stars receive a certificate of achievement and are on the path to becoming Community Leaders.
January 9, 2020

WOW! Great additional article @Peter Jessen ! Between you and Tim there are now many great articles to share with my Rotterdam Community Members!! 😎👍

Thank you 🙏😇

Like # people like this
Tarun Sapra
Atlassian Team
Atlassian Team members are employees working across the company in a wide variety of roles.
February 5, 2020

Lot of great insights. Thanks for sharing this.

jenny.bellas October 8, 2020

Hi @Peter Jessen  - We have "made the switch" of having our Jira Defects create Jira Align Stories (type = Defect) instead of creating Defects, for all the reasons you mention above. A problem that we see though is that all the rich Jira Align reporting seems to only report on Defect #s, not Story (type = Defect) #s. We are very interested in reporting on the quality of our release vehicles, the quality of our programs, and quality over time. Do you have any suggestions for us? Thanks in advance.

Like # people like this
Peter Jessen
Rising Star
Rising Star
Rising Stars are recognized for providing high-quality answers to other users. Rising Stars receive a certificate of achievement and are on the path to becoming Community Leaders.
April 5, 2021

Hi @jenny.bellas - Apologies for the long hiatus and lack of response.

You are correct. The trade off with moving the the Story of Type Defect approach is that you lose all of the rick quality reporting in Align by not using the out of the box defect functionality Align provides.

The challenge is that the defect/QA functionality was built when Align was an independent scrappy startup - AgileCraft. The functionality was built when it was assumed clients would use AgileCraft for QA functionality, so the ability to maintain the flow of defects into and out of AgileCraft via the connector (while maintaining the same external ID) was built out.

The crux of the issue is that Align treats defects as they were meant to be treated in agile - as something that needs triage to determine if it is a real defect or a user issue. It then requires the  defect to be promoted/converted to a story in Align to be prioritized, sized, and worked as a normal story (just one found via defect path vs new feature functionality). This causes the Jira bug to come in(one-way) to Align, map to the defect functionality, strip the meta-data (epic link, team, sprint, etc.), get promoted to a story after triage (which causes it to appear as a new story of type defect in Align and syncs to Jira as a defect/bug), which results in "duplicate" bugs/defects in Jira with different Jira IDs. Yuck!

I'm hoping Atlassian is working on a solution to this issue, as you are not the first client to raise the trade-off issues of using the story of type defect approach. In fairness to all involved, most clients using Jira for the team level are also using a test suite for defects that connects to Jira in some way, so they rely on the quality reporting those other systems provide.

That being said, it would be wonderful to see Atlassian solve for the very tough nut of providing the rich quality reporting from Align when integrated with Jira.


NOTE: What's the difference between a bug and defect? Is there any? Yes, there is. A bug is something found by the team during development and prior to Product Owner acceptance. It is used a way to communicate between the tester and developer (Hey! You've got a few bugs to squash in your code.)  A defect is any issue that appears or is reported after the story/code has be accepted by the Product Owner. Most organizations using Jira use the single bug issue type for both (very different) concepts.

bas.burgers April 2, 2022

Hi @Peter Jessen ,

In our Jira Align we have bugs mapped to stories of type defect. Does this also mean that the workflows of stories and bugs need to be identical ? In our case there is a mapping specified for stories, but not for bugs.

Assuming the story and bug workflows need to be the same, how can the Jira Align "ready to start" state for stories be used. Having such a "Ready to start" state for bugs doesn't make much sense.

We would like to add a "ready to start" state in the Jira story workflow and map it to the Jira Align state. We don't want a ready to start state for our bug workflow but still want to map bugs to stories of type defect. Is that possible ?

Like julie.janak likes this


Log in or Sign up to comment
AUG Leaders

Atlassian Community Events