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

View the Jira Align "Why" Field in Jira Software

You can configure your Jira integration to display information found in Jira Align's Why button directly in a Jira Software Epic (This sync will only apply to Jira Epics and not Stories). This is useful for seeing how an epic contributes to capabilities, themes, and the overall strategy.


  • Data syncs one-way, from Jira Align to Jira Software. Some Jira Software configurations may make the Why field appear editable in Jira, but any changes made will be overwritten upon the next sync with Jira Align. 
  • The data from the Why button only syncs to Jira Software when a work item in Jira Align is updated and saved. Progress data is from related work items is not automatically synced.
  • The new issue view in Jira Software is recommended for better visibility of Why data.

Create a custom field in Jira Software

To bring Why data from Jira Align into Jira Software, you must first create a custom field in Jira Software. The custom field type must be Text Field (multi-line). Give the new field a familiar name, such as Jira Align Why Definition. 


Once the custom field has been created, obtain its Custom Field ID. In Jira Software, search for the field under Settings > Issues > Custom Fields. Once located, click the ... menu icon in the upper-right and select Edit or Configure. In the resulting page, the Custom Field ID can be found at the end of the URL in your address bar. For example:!default.jspa?customFieldId=100xx

Connect the Why field in Jira Align

To connect Why data to your Jira Software custom field, log into Jira Align and navigate to Administration > Connectors > Jira Settings > Jira Setup > Custom Fields. Next, scroll down to the Why? Details field and enter your custom field ID in the following format: customfield_100xx, where "100xx" is the ID located in Jira Software. 



Notes: The "Why Button" sync is currently behind a Feature Toggle within Jira Align and will need to be activated by a Jira Align Support Engineer or Solution Architect prior to rendering under Administration > Connectors > Jira Settings > Jira Setup > Custom Fields

Data Displayed

Once the Why field is configured, the following data will be displayed in the custom field when viewing an epic in Jira Software:

  • Associated work items: Epic, Capability, and Theme, when present 


Shawn Kessler
Atlassian Team
Atlassian Team members are employees working across the company in a wide variety of roles.
Feb 05, 2020

Great article @Tim Keyes ! The Why button is a very powerful tool in Jira Align for showing parent work items, success measurements, and business cases linked to the target. It is often under used, so hopefully this article will make more users aware of it ;)

Like # people like this
Mark Cruth
Atlassian Team
Atlassian Team members are employees working across the company in a wide variety of roles.
Apr 03, 2020

Here are the fields you need to enter to populate the Success Measurement and Business Case on the Why Button...

Success Measurement

  • Populated from adding a Success Criteria to a Jira Align Epic 
  • Uses both the Problem Statement and Success Criteria Fields

Business Case

  • Populated from the Benefits Tab on a Jira Align Epic
  • Uses the Current Situation, Recommendation & Desired Solution, and Future State & Desired Outcome fields
Like # people like this

We have added this but then noticed that the sync from Align to Jira only happens when an Align Epic is updated. If we were to only update the Epic's parent task such as the Initiative linked to the Epic it does not sync the Why button details to Jira.  Is this expected behavior? 

Another issue is that the percentage showing as completed on the Why button for Initiative (showing as 0%) is not what is there on the initiative itself (which shows 50%). Happy to raise a support ticket if you think this is a bug. 



Hi @Tim Keyes , I cannot manage to see the "Why ? Details" mapping anymore in the current Jira Align settings > Jira setup. Is it because this functionnality was removed ?

Best Regards,


Tim Keyes
Atlassian Team
Atlassian Team members are employees working across the company in a wide variety of roles.
Jun 02, 2021

Hi @Hina Tufail

Thank you for the question.  The "why button" setup field appearing under Jira Align Admin > Jira Settings > Jira Setup is tied to a Jira align Feature Toggle that the Jira Align support team can help you enable.  It is possible that that toggle was enabled on a Jira Align site you were using but disabled on your current site.  

You can submit a support request to to receive additional assistance on having the toggle enabled for your instance.

Thank you!

Like Hina Tufail likes this

@Tim Keyes can we do this using Azure DevOps as well?

Is anyone aware of a way to make this custom field render the text from the Why into a table like it would in the description of a jira issue? It's really hard to read when not rendered properly.


@Tim Keyes 

@Liza Merriman, you need to change the custom field renderer in Jira:

Jira Admin -> Issue Settings -> Field Configuration -> select field -> Renderers -> Choose "Wiki Style Renderer"


Log in or Sign up to comment
AUG Leaders

Atlassian Community Events