Showing results for 
Search instead for 
Did you mean: 
Sign up Log in

Earn badges and make progress

You're on your way to the next level! Join the Kudos program to earn points and save your progress.

Deleted user Avatar
Deleted user

Level 1: Seed

25 / 150 points

Next: Root


1 badge earned


Participate in fun challenges

Challenges come and go, but your rewards stay with you. Do more to earn more!


Gift kudos to your peers

What goes around comes around! Share the love by gifting kudos to your peers.


Rise up in the ranks

Keep earning points to reach the top of the leaderboard. It resets every quarter so you always have a chance!


Come for the products,
stay for the community

The Atlassian Community can help you and your team get more value out of Atlassian products and practices.

Atlassian Community about banner
Community Members
Community Events
Community Groups

Jira and Jira Align Integration: Configure Custom Issue Type Mapping and Stories of Type Defect

Custom issue types in Jira can be mapped to Jira Align stories of select types.  


Mapping Custom Issue Types in Jira Align:

Navigate to Jira Align Admin section > Jira Settings > Custom Issue Types panel > Click Add and input the Name of any Custom Issue Types that you would like to synchronize with a Jira Align Story of the selected Type then select the matching Jira Align Story Type from its corresponding drop-down then click Save.  The selector toggles are used to select and Delete a Custom Issue Type. They do not need to be utilized when adding Custom Issue Types.

Note: There needs to be a one to one mapping between Custom Issue Types in Jira and Story Types in Jira Align or data will not sync properly.  



Defining Custom Issue Types in Jira Align:

Custom Story Types can be defined by navigating to Jira Align Admin > Platform > Dropdowns Panel > Story Type




Custom Issue Type Fields and Filtering

Custom Issue Types that are integrated with Jira Align will sync in the same manner as traditional Jira Stories except that the Jira Align type field on the Story will reflect what Type of Story was integrated.  The fields that sync between Jira and Jira Align on Stories and Custom Issue Types can be found here:

Stories can be filtered in the Jira Align Stories Grid base off of the Type field as show below.


Stories of Type Defect

The Jira Align Defect has a separate Backlog than Jira Align Stories meaning that Jira Align Defects cannot be linked to Jira Align Features (Jira Epics) or have their Story Points vertically aggregate to the Enterprise Level.  More information can be read on the Jira Align defect here:

Some organizations would rather be able to Link their Jira Bugs to Jira Epics and synchronize Story Points on Bugs from Jira to Jira Align so it makes more sense for them to sync Jira Bugs to Jira Align Stories of Type Defect instead of the native Jira Align Defect.  

If syncing the Jira Bug to the Jira Align Defect these fields should be populated under Jira Align Admin > Jira Settings > Jira Setup


If syncing the Jira Bug to the Jira Align Story of Type Defect the above fields should be left blank and the following fields should be populated under Jira Align Admin > Jira Settings > Custom Issue Types


The Jira Align Story of Type Defect will function as a normal Jira Align Story outside of having a Type Defect. If you original setup the connector to sync Jira Bugs to Jira Align Defects and wish to convert to Story of Type Defects you can null out the Bug to Defect mapping and populate the Custom Issue Type mapping then run a custom JQL to update all data.  Information on custom JQLs can be found here:


Hello, thank you for the article! Wanted to let you know that I am unable to see the photos attached to this article.

missing photo.JPG

Like # people like this
Tim Keyes Atlassian Team Jan 06, 2020

Hi Esme,

Thank you for the note.  Can you please check again.  I have removed and readded the images.



Tim Keyes

Like Shawn Kessler likes this

Hi Tim, 

I checked again and I am still unable to view the images.



Tim Keyes Atlassian Team Jan 06, 2020

Hi Esme,


Can you please verify if you can see them now?

I was originally hosting the images internally on the Atlassian Network and have made them public through public hosting. 

Thank you for the assistance, it is greatly appreciated!

Tim Keyes  

Like # people like this

Hi Tim,

Yes, I am able to see them now! 



Hi @Tim Keyes,

Nicely written article. Of course, I didn't see it until after I wrote up this related one.


Like # people like this

@Peter Jessen Never a bad thing to have as MUCH knowledge from different perspectives on Community. Nice job!! And great knowledge share! #KUDOS

Like # people like this

@Tim Keyes , how does align handle the resolution field in JIRA? I did not see even a reference to it.

Hi Reza,

Thank you for the question. 

Jira Align will treat the resolution differently for defects and stories.

Additional information can be found in this article:

  • If a bug in Jira Software is in any status other than Resolved, the defect's status will be Open in Jira Align.
  • If a bug's Resolution is set to Done in Jira Software, the Defect will be set to Closed in Jira Align.
  • The Accepted state for stories is not configured on this panel, as the Accepted status from Jira Software to Jira Align is based off of the Accepted Date field.  The Accepted Date field is configured in the Jira Align Administration > Jira Settings > Jira Setup tab in the Custom Fields section.
  • A combination of Done + Resolution states in Jira Software is required in order to transition a story's state to Accepted in Jira Align.

Please let us know if you have any additional questions.


Hi @Tim Keyes ,

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 ?

Tim Keyes Atlassian Team Apr 03, 2022

Hi @bas.burgers

Thank you for the question! I hope all is well!

When Jira Bugs are mapped to a custom issue type (story type defect) they will adhere to the story status mapping. When Jira Bugs are mapped to the Jira Align Defect they will adhere to the Defect status mapping. So you should only need to map the Story status.

It is not possible to modify the Jira Align Statuses but you can leverage process flow mapping to better tie your Jira workflow to a corresponding Jira Align workflow.  The process flow (process step) mapping is further discussed here:

You could map a single Jira State to multiple Jira Align Statuses to avoid adding a "ready to start" state in Jira.  You could also leverage the process steps mentioned above.

I hope this helps!


Log in or Sign up to comment

Atlassian Community Events