006-Additional Issue hierarchies

Now we can define an additional hierarchy in the following way:

Now if you will select and import the Feature custom issue link field then also the corresponding additional Feature hierarchy will be defined for the Issue dimension.

Examples

Hierarchy with epics and themes

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 or themes then you can define the following hierarchy.

Let's assume that epics are linked to themes (with the Theme issue type). Then at first you can define an issue link custom field:

As we have specified to update customfield_theme from epic_key then all stories and story sub-tasks within the epic will have the corresponding customfield_theme as well.

Then we can define an additional hierarchy with Theme, Epic, Parent and Sub-task levels:

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:

Portfolio for Jira hierarchy import (one level above Jira epics)

When Portfolio for Jira solution is used, there could be invented a new summary level (or several) above epics in the Portfolio structure, for example, Initiative or Program. To analyze data by this level, you may want to import corresponding issue type as a new hierarchical level to roll up values from lower level issues.

Let's say we have a new level Initiative (based on issue type Initiative) above epics in Portfolio, and the full structure is Initiative - Epic - Story - Sub-task. To import this structure as a new hierarchy in eazyBI Issue dimension, do the following steps.

   1. Get a custom field with Initiative issue key.

To import a new hierarchy level you should use the key of parent issue. Using Portfolio, parent issue information (in this case, Initiative) is stored in the custom field "Parent link".  Examine this field in Epic issue screen in Jira.

1. 1. If "Parent link" field contains only Initiative key (without initiative name), you can use "Parent link" custom field for the next step.

   2.  If the field contains Initiative key together with initiative name or another information, create a new scripted custom field "Initiative" to extract parent Issue key from Parent Link. For example, you can use Jira Misc Custom fields add-on calculated text custom field with the following code:

Use Parent link custom field ID instead of NNNNN in the formula above.

    2. Add custom field definition and hierarchy definition to advanced settings in eazyBI.

Add the following advanced settings for the custom field representing Issue key of Initiative issue in eazyBI to define the new hierarchy:

Instead of customfield_AAAAA, use ID of the custom field containing Inititative key (either Portfolio custom field "Parent link" or scripted custom field "Initiative"). Also, use correct issue_type.

You can use values in name sections according your needs.

   3. Import the new hierarchy in eazyBI.

Once the both custom field and hierarchy definitions are added to eazyBI advanced settings, please select the custom field "Parent Link" or "Initiative" as a property for import and run an import. Import will create a new Issue dimension hierarchy in your account.

Hierarchy with several levels above standard 

When there are several Portfolio for Jira summary levels above epics (or parent issue if epics are not used) in the Portfolio structure or this multi-level hierarchy is maintained by issue links, you my want to import corresponding issue types as new hierarchical levels to roll up values from lower level issues.

General approach

1. In general, to create a new hierarchy, each lower level issue should know all it's parent and grandparents issue keys (for instance, a sub-task should "know" its task, theme, initiative, and programm issue keys).
   Most usually, each issue has its parents key only, and then the value should be inherited to lower level issues during data import from Jira to eazyBI. This chain must be defined in advanced settings using setting update_from_issue_key (see below).
   
   
2. To create a hierarchy, each issue type should be included only in one hierarchy level. To ensure that, parent issue keys from different issue types (programms, initiatives, themes) should be retrieved in separate custom fields: each custom field would be used to define a particular level in the hierarchy. 
   Information about the parent issue type is not stored in the child issue data, therefore, it should be already precalculated in Jira, using some scripted field, for instance, Jira Misc Custom fields add-on.
   
   
3. Instead of Portfolio Parent link, you may use other ways how to store issue parent issue key: specific custom fields or Jira issue links. The general principles stay the same: define a separate custom field for a parent link from a specific issue type (or types) that is inherited to the lower level issues. Inheritance could be maintained in Jira by scripted fields or during data import to eazybi according to the definition in advanced settings.
   
   

Importing more than one hierarchical level above the standard issue hierarchies might be complex. Please, contact support@eazybi.com if you need assistance with that!

Example with Jira Portfolio

Let's say, you have a hierarchy Initiative - Programm - Theme - Epic - Story - Sub-task, where all levels above Epic are Portfolio levels.

1. Get custom fields with parent issue keys.

Create three custom fields to retrieve initiative, programm, and theme issue keys. In Jira, each issue would have a value only in one field (accordingly to its parent issue type), values in other custom fields would be calculated during data import.

For example, you can use Jira Misc Custom fields add-on calculated text custom field. The code for all three custom fields is almost the same, only use correct parent issue type name in  issuetypename.equals function.  

The following code would retrieve "Programm" issue type parent issue key from Portfolio Parent link field:

Use Parent link custom field ID instead of NNNNN in the formula above.

   2. Add custom field definition and hierarchy definition to advanced settings in eazyBI.

Add the following advanced settings for the custom field representing Issue key of Initiative issue in eazyBI to define the new hierarchy

Instead of customfield_AAAAA, customfield_BBBBB, and customfield_CCCCC, use corresponding IDs of the custom fields containing Parent Initiative, Programm, and Theme issue keys. Also, use correct issue_type.

You can use values in name sections according your needs.

 3. Import the new hierarchy in eazyBI.

Once the definitions of custom fields and hierarchy are added to eazyBI advanced settings, in eazyBI import setting screen, select all three custom fields as properties for import and run data import. Import will create a new Issue dimension hierarchy in your account.

Troubleshooting

There might be cases when issue configuration parameters seems 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 build 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 use the Inward end of the link in this case to build the hierarchy level 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 troubleshhoot the most common problems with issue link import, read in Import issue links troubleshooting article.
2. Create a test report to check whether parent issue keys are imported correctly for each issue: use issues in rows and properties containing issue parent key in columns. In that way you ensure that parent key import is correct. 
   
   Once the properties contain correct keys of the parent 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. The hierarachy might not show up also when other configuration parameters are wrong. Please check, if you have correct configuration parameters: update_from_issue_key for the custom field,  key_column for the hierarchy, and Issue type.

   1. Rules for defining update_from_issue_key correctly:

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

      2.  if the next lower level is Epics, use 
         update_from_issue_key = "epic_key"

      3.  if the next lower level is a standard issue level (parent), set
         update_from_issue_key = "parent_issue_key"

   2. Rules for defining key_column correctly:
      1. 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. if the hierarchy is defined upon sub-task hierarchy
         

          {name="Task",key_column="subtask_parent_key"},
          {name="Sub-task",key_column="subtask_key"}

         
         

5. Use check_calculated_value setting if custom fields you use for creating the new hierarchy are scripted fields or Jira Portfolio Parent link field. It would guaranty that the changed link between upper level issues would be changed also in the inheritance chain.