Additional Issue hierarchies
eazyBI for Jira
This page describes advanced Jira and eazyBI integration. If you need help with this please contact eazyBI support.
On this page:
Configuration
The Issue dimension has several standard hierarchies that group the issues. Those hierarchies allow eazyBI to sum all the measures at any higher level. You can read more about issue hierarchies here.
The standard Issues hierarchies are:
- the default hierarchy with Project and Issue levels,
- the Sub-task hierarchy with Project, Parent and Sub-task levels,
- and if you have imported the standard Epic Link field then also
the Epic hierarchy with Project, Epic, Parent and Sub-task levels. - the Parent hierarchy with Issue Type Hierarchy levels defined in Jira. For Jira Data Center, those level names are created automatically; for Jira Cloud, additional configuration is needed.
eazyBI supports building custom hierarchies in Issue dimensions with several levels on top of default sub-task or epic hierarchy and Project level. You would like to define and use one custom field for any level on top of default ones. Describe any next level from the child's perspective. eazyBI supports hierarchies with strict structures. Issues with the same issue type should be on the same level. Any issue could be in one branch only - 1 to many relationships for parent-child only on all levels.
You can define additional Issue dimension hierarchies using the issue fields that are imported. Quite often, additional hierarchies are defined using imported issue link custom fields.
Additional hierarchies are defined in eazyBI advanced settings and are marked with the setting issue_hierarchies.
As an example, let's create additional Theme hierarchy with Theme, Parent and Sub-task levels. Let's assume that we have an issue links from stories to themes and we have already configured a custom field for this issue link:
[jira.customfield_theme] name = "Theme" inward_link = "is child of" issue_type = "Theme" update_from_issue_key = "parent_issue_key"
Now we can define an additional hierarchy "All Issues by themes" in the following way:
[[jira.issue_hierarchies]]
name = "Theme"
all_member_name = "All Issues by themes"
levels = [
{name="Theme",key_column="customfield_theme",issue_type="Theme"},
{name="Parent",key_column="subtask_parent_key"},
{name="Sub-task",key_column="subtask_key"}
]
Now if you will select and import the Theme custom issue link field then also the corresponding additional Theme hierarchy will be defined for the Issue dimension.
Examples
Hierarchy with epics and Features
If you are using Jira Software (former Jira Agile) epics (and have imported Epic Link custom field) and are linking epics to higher level features then you can define the following hierarchy.
Let's assume that epics are linked to features (with the Feature issue type). Then at first you can define an issue link custom field:
[jira.customfield_feature] name = "Feature" inward_link = "Parent Feature" issue_type = "Feature" update_from_issue_key = "epic_key"
As we have specified to update customfield_feature from epic_key then all stories and story sub-tasks within the epic will have the corresponding customfield_feature as well.
Then we can define an additional hierarchy with Feature, Epic, Parent and Sub-task levels:
[[jira.issue_hierarchies]]
name = "Feature"
all_member_name = "All Issues by features"
levels = [
{name="Feature",key_column="customfield_feature",issue_type="Feature"},
{name="Epic",key_column="epic_key"},
{name="Parent",key_column="epic_parent_key"},
{name="Sub-task",key_column="subtask_key"}
]
This example is described in Troubleshooting as well.
Epic hierarchy without projects
In Issue dimension Epic hierarchy, epics are split by projects based on their stories, therefore, epics could be included in the report more than once. To avoid splitting them by projects and, meanwhile, use benefits of Issue dimension Epic hierarchy, you can define Issue dimension Epic hierarchy without project level.
If you are using Jira Software (former Jira Agile) epics (and have imported Epic Link custom field), you do not need to define a new custom field, just define hierarchy levels based on the existing levels. Add the following advanced settings:
[[jira.issue_hierarchies]]
name = "Epics without project"
all_member_name = "All Issues by epics without project"
levels = [
{name="Epic",key_column="epic_key"},
{name="Parent",key_column="epic_parent_key"},
{name="Sub-task",key_column="subtask_key"}
]
Separate hierarchy level for Story between parent and epic
If there is some change for Epic level or an additional level comes between Epic and Parent issues, like a separate level for Story, then Epic level should be redefined.
In the given example is a hierarchy for Features → Epics → Stories → the rest of the issue types like Bugs, Task, etc. → Sub-tasks.
[jira.customfield_featuree]
name = "E Feature"
inward_link = "is child of"
issue_type = "Feature"
dimension = true
update_from_issue_key = "customfield_epice"
[jira.customfield_epice]
name = "E Epic"
inward_link = "has Epic"
issue_type = "Epic"
update_from_issue_key = "customfield_storye"
dimension = true
[jira.customfield_storye]
name = "E Story"
inward_link = "is caused by"
issue_type = "Story"
update_from_issue_key = "parent_issue_key"
dimension = true
[[jira.issue_hierarchies]]
name = "Features by Stories"
all_member_name = "All Issues by Features"
levels = [
{name="Feature",key_column="customfield_featuree",issue_type="Feature"},
{name="Epic and risk",key_column="customfield_epice",issue_type="Epic"},
{name="Story",key_column="customfield_storye",issue_type="Story"},
{name="Parent",key_column="subtask_parent_key"},
{name="Sub-task",key_column="subtask_key"}
]
Hierarchy with fewer levels than the original Parent hierarchy
The eazyBI for Jira Cloud Parent hierarchy expects all Issue type hierarchy levels to be defined in the eazyBI advanced settings to create a Parent hierarchy. In case there is a need to have a hierarchy with fewer levels than the original one, you can use this configuration:
[[jira.issue_hierarchies]]
name = "Plans by Feature"
all_member_name = "All Issues by Feature"
levels = [
{name="Feature",key_column="jpoh_parent_3",issue_type="Feature"},
{name="Epic",key_column="jpoh_parent_2",issue_type="Epic"},
{name="Parent",key_column="jpoh_parent_1"},
{name="Sub-task",key_column="subtask_key"}
]
"jpoh_parent_X" identifies the original Parent hierarchy levels. Use a parent level number 1,2,3,.. instead of X counting parent levels on top of sub_tasks. 1 for story/standard issue level (jpoh_parent_1), 2 for epic level (jpoh_parent_2), 3 ...
Troubleshooting
There might be cases when issue configuration parameters seem not working as expected, and debugging is needed. Here are hints that might help faster find out why hierarchy does not appear.
- If your hierarchy is built on issue links, check if you have correctly used inward_link or outward_link.
The general rule is to build the hierarchy with the link from the child's perspective. For instance, if you need to link Epics to a higher-level Feature you could have defined the link as shown in the image. You should open Epic and define a reference to Feature (higher level) from Epic (children) perspective. In case, Epic has a link Parent Feature (inward description of the link). You should use the Inward end of the link (inward_link = "Parent Feature"), in this case, to build the hierarchy-level Feature above the Epic since it is the way how the Epic is linked to the Feature.
Incorrect issue link definition is one of the causes for failing issue hierarchy. How to troubleshoot the most common problems with issue link import, read in Import issue links troubleshooting article. - Create a test report to check whether higher level issue keys are imported correctly for each issue: use issues in rows and properties containing issue link custom fields used in the hierarchy in columns. In this case, Epic D11-45 has link to Feature PO-2.
Once the properties contain correct keys of any higher level issues of intended hierarchy you can proceed with the hierarchy configuration parameters. - Whenever you change the advanced settings for a custom field or hierarchy, it is recommended to either do a full data reimport in the account, or to clear the previously loaded custom field configuration (run the import with the custom field un-checked) and load it again (run the import with the custom field checked).
- eazyBI can't build hierarchy if any defined level has a parameter
multiple_values = true. Build issue hierarchy based on one of the two default hierarchies (epic hierarchy or sub-task hierarchy). Parameters update_from_issue_keys and bottom levels the hierarchy should be of the same default hierarchy and should be used with default setup. Build any level on top of those bottom levels.
Rules for defining update_from_issue_key correctly:
when define any higher level link custom field, link it to the field storing issue key of the next lower issue level
if the next lower level is Epics and the hierarchy is defined upon epic hierachy, use
update_from_issue_key = "epic_key"if the next lower level is a standard issue level (parent) and the hierarchy is defined upon sub-task hierarchy, set
update_from_issue_key = "parent_issue_key"
- Rules for defining bottom levels of the hierarchy correctly:
use those as bottom levels if the hierarchy is defined upon epic hierachy
{name="Epic",key_column="epic_key"}, {name="Parent",key_column="epic_parent_key"}, {name="Sub-task",key_column="subtask_key"}use those as bottom levels if the hierarchy is defined upon sub-task hierarchy
{name="Parent",key_column="subtask_parent_key"}, {name="Sub-task",key_column="subtask_key"}Don't specify the issue_type for bottom levels; leave them as they are shown in the examples.