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: Jira Issue Field Best Practices

Best Practice #1:

In preparation for integrating projects in Jira with Jira Align, it is necessary to confirm that the fields that will be synced between the two are present on the Create and Edit screens in Jira for each of the issue types.


When an item is created or edited in Jira Align and then syncs to Jira, the synced fields need to be present in Jira for the connector to pass the info through.  If these fields are not present, syncs from Jira Align to Jira will fail.

Action to take:

Perform the following steps in Jira for each issue type.

1.  Navigate to a project that will be integrated

2.  Click Project Settings and then Screens

3.  Select the Screen listed for Create Issue or Edit issue

Screen Shot 2020-11-18 at 12.41.42 PM.png

4.  Confirm appropriate fields are listed.  These are the minimum fields to sync from Jira Align to Jira.  There could be more fields listed.

  • Epics
    • Name
    • Summary
    • Description
    • Estimate (Points)
    • Acceptance Criteria
    • Assignee
    • Status
    • Fix Version (if used)
    • Labels
    • Issue Type
    • Reporter
    • Program Increment (optional custom field)
    • Parent Jira Epic Name (optional custom field)
    • Why? (optional custom field)
  • Stories
    • Summary
    • Description
    • Estimate (Points)
    • Parent Epic
    • Acceptance Criteria
    • Assignee
    • Status
    • Fix Version (if used)
    • Issue Type
    • Labels
    • Epic Link
    • Reporter
    • Sprint
    • Assigned Team (optional custom field)
  • Sub-Tasks
    • Summary
    • Description
    • Assignee
    • Parent Story
    • Reporter
  • Bug
    • Summary
    • Description
    • Estimate (Points)
    • Assigned Team
    • Sprint
    • Assignee
    • Priority
    • Status
    • State
    • Fix Version

5.  If a field isn't listed, use the dropdown at the bottom to add the missing field

Screen Shot 2020-11-18 at 12.58.00 PM.png

For projects that do not share the same Screen Schemes, the steps above will need to be repeated for those projects


Best Practice #2:

Fields that are NOT synced between Jira Align and Jira cannot be marked as required in Jira.


If an item is created in Jira Align and there is a required field in Jira that does not sync with Jira Align, the sync will fail and the item will not be created in Jira.  This is because Jira is looking for the connector to pass this info from Jira Align but it doesn't exist in Jira Align.  Since Jira sees this as a required field for creation, it will not create it.  This is most common with custom fields.

Action to take:

Perform the following steps in Jira.

1.  Click on the Settings cog

2.  Select Issues

Screen Shot 2020-11-18 at 4.36.39 PM.png

3.  Select Field configurations

4.  Select the appropriate Field Configuration

Screen Shot 2020-11-18 at 4.40.18 PM.png

5.  Review the list and confirm any fields that are marked as required are fields that can be synced.  Reference list above.  If fields are not synced via the connector, they must be changed to Optional.

Screen Shot 2020-11-18 at 5.03.33 PM.png

Best Practice #3

Required Jira fields that ARE synced between Jira Align and Jira must have a value entered in Jira Align when initiating the sync from Jira Align.


If an item is created or updated in Jira Align and there is a value missing in a Jira Align field that syncs with a field that is required in Jira, the sync will fail and the item will not be created or updated in Jira. Similar to Best Practice #2, Jira is looking for the connector to pass this info from Jira Align, but it is not present. Since Jira sees this as a required field, it will not create or update the issue without it.

Action to take:

Make the field required in Jira Align as well. Doing this will help ensure the field stays populated and requirement of fields can be controlled by Portfolio. This can only be done by a user that has the appropriate permissions to access the Details Panels Settings in the Jira Align Admin Console. 

Screen Shot 2022-02-02 at 1.15.38 PM.jpg


There are a few exceptions where Jira Align may not enforce the required field:

  • when a work item is created or updated via the API
  • when a work item is created or updated via an import
  • when a work item is created or updated via its parent work item's Quick Add Feature

The above will generate an entry in the Audit Log of the Jira Align work item indicating that it failed to sync to Jira


Related Articles


Paul Flynn Atlassian Team Jan 11, 2021

@Rae Gibbs   Under Epic where you have 

  • Parent Jira Epic Name (optional custom field)

Is this meant to be the Jira Align Epic or Capability?  

Rae Gibbs Atlassian Team Jan 12, 2021

@Paul Flynn Yes.

@Rae Gibbs Under stories you have Assigned Sprint and Sprint.  Not sure I understand the difference.  Unless by Assigned Sprint (Custom field) would be what was planned in JA and Sprint (Jira Standard) is where it actually is? 

Rae Gibbs Atlassian Team Jan 18, 2022

@Timothy Beran That was just a mistake on my part. There should only be one Sprint field. It is called Assigned Sprint in Jira Align and Sprint in Jira. Those fields are the same and sync with each other.

Like Timothy Beran likes this

Do Jira TASKs (not subtasks) that are part of an epic sync from Jira to Jira Align?

@Rae Gibbs Thank you for this article! Are there any plans to map/sync the Severity field? Maybe similar to how Priority can be sync'd?

 Screen Shot 2022-10-25 at 2.46.31 PM.png

@Scott Grossman You may have already found this answer, but yes. You can set up other issue types to come on over to Jira Align from Jira. Jira custom issue types are converted to a "Story of type ..." 
For example in your case, a Jira Task would appear as a Story of type Task in Jira Align.

First, set up the types in Jira Align here: Administration > Platform > Dropdowns section.

Then configure the mapping in Jira Align here: Administration > Jira Settings > Custom Issue Types tab

 You'll need to know the Jira custom issue type IDs. 

Rae Gibbs Atlassian Team Oct 26, 2022

@Tracy Walton I have not heard any mention of that. There was a Community Article put out by Head of Product for Jira Align about some changes coming in the near future with the connector and that was not listed.

Like Tracy Walton likes this


Log in or Sign up to comment

Atlassian Community Events