Additional Issue hierarchies

This page describes advanced Jira and eazyBI integration. If you need help with this please contact eazyBI support.

Available from eazyBI version 4.1.


On this page:

Configuration

The Issue dimension has the following standard hierarchies:

  • the default hierarchy with Project and Issue levels,
  • the Sub-task hierarchy with ProjectParent and Sub-task levels,
  • and if you have imported the standard Epic Link field then also
    the Epic hierarchy with ProjectEpicParent and Sub-task 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.

As an example, let's create additional Theme hierarchy with ThemeParent 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 in the following way:

[[jira.issue_hierarchies]]
name = "Theme"
all_member_name = "All Issues by themes"
levels = [
  {name="Feature",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 FeatureEpicParent 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"}
]


Troubleshooting

There might be cases when issue configuration parameters seem not working as expected and debugging is needed. Here follow hints which might help faster find out the reasons why hierarchy does not show up.

  1. If your hierarchy is built on issue links, check if you have correctly used inward_link or outward_link. 
    The general rule is that you should build the hierarchy with the link from the child perspective. For instance, if you need to link Epics to a higher level Feature you could have defined 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. You should use the Inward end of the link, 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.


  2. 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.

  3. 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).

  4. eazyBI can't build hierarchy if any defined level has a parameter multiple_values = true.

  5. 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.

    1. Rules for defining update_from_issue_key correctly:

      1.  when define any higher level link custom field, link it to the field storing issue key of the next lower issue level

      2.  if the next lower level is Epics and the hierarchy is defined upon epic hierachy, use 
        update_from_issue_key = "epic_key"

      3.  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"

    2. Rules for defining bottom levels of the hierarchy correctly:
      1. 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"}

      2. 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"}