Follow these steps to use your existing Jira projects in Agile Hive


1. Project Structure

Introduction

Let us start with the structure of your projects. Each Portfolio, Solution, ART and Team needs his own Jira project.
On the right side
 you can see an example of what a project structure looks like.

With the help of the Agile Hive Project Hierarchies, you can map the four SAFe levels (Portfolio, Large Solution, ART and Team) as well as the business units located therein.

The SAFe levels are represented as horizontal layers. The business units (Jira projects) are shown as colored diamonds within the layers.

If you've never used Agile Hive before, be sure to read the Getting Started page first:

Getting Started

Scenario 1 - The ART and its teams each have their own projects

Step 1

Add the ART and the team projects into the correct layers of the Agile Hive Project Hierarchies and set up the relationship between them.

Step 2

Make sure that every team uses a Scrum Board (also Kanban Teams).

Now set this Scrum Board as 'Primary board' of the team in the project configuration.

If a PI is already in progress also click on the button 'Recreate missing sprints'. This will create all missing sprints of the current PI in the Scrum Board of that team.

Done

Now we have to take care of the Jira issues.

Migrate Issues & Convert Links


Scenario 2 - The ART & its teams share a project

Let's go through this together using a typical scenario. The Agile Release Train (ART) and the teams all share a project. The assignment of issues to teams is done using labels or a custom field. How should I proceed?

Step 1

Create a new project for each team by using the 'SAFe Team Project' Template.

Step 2

Move the team level issues (like stories etc.) into the corresponding team project by using JQL and the move functionality of Jira.

Step 3

Add the ART and the team projects into the correct layers of the Agile Hive Project Hierarchies and set up the relationship between them.

Done

You have successfully separated the ART project from the team projects and put them in real relation to each other.

Now we have to take care of the Jira issues.

Migrate Issues & Convert Links


2. Migrate Issues & Convert Links

Introduction

This section shows you how to change issue types and issue links so that they work in harmony with Agile Hive & SAFe.

Migrate Jira Epics to Features (or any other issue type)

This is the typical scenario that is often used by customers: The ART project uses Jira Epics to actually represent SAFe Features. 
Enablers and other issue types cannot be used (correcly) because there is only one epic type in Jira.

Important note: The stories are already in the respective team projects. If not, please follow the instructions in the 'Project Structure' section above.

Since Agile Hive uses the "Agile Hive Link" for hierarchical links and this is the connecting link for all aggregations, the Jira Epic links must be changed to the Agile Hive Link using the Scriptrunner script available below. In addition, the Jira Epics must be changed to a SAFe-compliant issue type that is automatically delivered by Agile Hive. 

Step 1

Install ScriptRunner for Jira and open the ScriptRunner Script Console (Jira Administration → Manage Apps → ScriptRunner → Script Console).


Step 2

Please first check with a JQL query the number of Epics that need to be changed and save the result.

issueFunction in hasLinkType("Epic-Story Link") AND issuetype = Epic AND issueLinkType not in ("Parent of")

Insert the script content on the right side into the Script Console.

Adjust the JQL in line 35 of the script so that only desired Jira epics are taken into account. Make sure that the JQL only contains Jira Epics.

Note: The script adds the Agile Hive Link to the Jira Epics. The Epic link to other issues remains at this point.

Execute the script via the "Run" button at the bottom.

Change Jira Epic Link into the Agile Hive Link Script

package scriptConsole

import com.atlassian.jira.bc.issue.link.IssueLinkService
import com.atlassian.jira.bc.issue.search.SearchService
import com.atlassian.jira.component.ComponentAccessor
import com.atlassian.jira.event.type.EventDispatchOption
import com.atlassian.jira.issue.Issue
import com.atlassian.jira.issue.IssueManager
import com.atlassian.jira.issue.MutableIssue
import com.atlassian.jira.issue.link.IssueLink
import com.atlassian.jira.issue.link.IssueLinkManager
import com.atlassian.jira.issue.link.IssueLinkType
import com.atlassian.jira.issue.search.SearchResults
import com.atlassian.jira.security.JiraAuthenticationContext
import com.atlassian.jira.user.ApplicationUser
import com.atlassian.jira.web.bean.PagerFilter
import groovy.transform.Field
import org.apache.log4j.Level
import org.apache.log4j.Logger

/**
 * Changes the Epic Links of Jira Epics into the Agile Hive Link.
 */

@Field Logger logger = (Logger) log;
logger.setLevel(Level.WARN);

@Field String LINK_DIRECTION_OUTWARD = "OUTWARD";
@Field String LINK_DIRECTION_INWARD = "INWARD";
@Field String LINK_NAME = "Agile Hive Link";
@Field String LINK_DIRECTION = LINK_DIRECTION_OUTWARD;

//JQL for the EPICs to be changed (Important! There may only be epics in the JQL)
@Field String EPIC_JQL = "project = XYZ AND issuetype = epic"

@Field List<Issue> epics = getAllEpics();
@Field IssueLinkType issueLinkType = getIssueLinkType(LINK_NAME);

IssueManager issueManager = (IssueManager) ComponentAccessor.getComponent(IssueManager.class);
for (Issue docIssue : epics) {
    MutableIssue epic = issueManager.getIssueObject(docIssue.getKey());
    handleIssue(epic);
    updateIssue(epic);
}
logger.debug("Done");

void handleIssue(Issue epic) {
    logger.debug("epic ${epic.key}");
    List<IssueLink> issuesInEpicLinks = getIssueLinks(epic, "Epic-Story Link", LINK_DIRECTION_OUTWARD);
    Set<Issue> issuesInEpic = getIssuesFromLinks(issuesInEpicLinks, LINK_DIRECTION_OUTWARD);
    for (Issue issue : issuesInEpic) {
        logger.warn("epic ${epic} issue ${issue} issuetype ${issue.getIssueType().getName()}")
            addIssueLink(issue, epic, getIssueLinkType(LINK_NAME));
    }
}

List<Issue> getAllEpics() {
    return getIssuesByJQL(EPIC_JQL)
}

List<Issue> getIssuesByJQL(String jqlSearch) {
    SearchService searchService = ComponentAccessor.getComponent(SearchService.class);
    ApplicationUser user = ComponentAccessor.getJiraAuthenticationContext().getLoggedInUser();
    logger.info("Searching JQL: ${jqlSearch}");
    SearchService.ParseResult parseResult = searchService.parseQuery(user, jqlSearch);
    if (parseResult.isValid()) {
        SearchResults searchResult = searchService.search(user, parseResult.getQuery(), PagerFilter.getUnlimitedFilter());
        return searchResult.getResults();
    }
    logger.error("JQL '${jqlSearch}' is invalid. ${parseResult.getErrors()}");
    return Collections.emptyList();
}

private void addIssueLink(Issue issue, Issue parent, IssueLinkType issueLinkType) {
    IssueLinkManager issueLinkManager = ComponentAccessor.getIssueLinkManager();
    issueLinkManager.createIssueLink(issue.getId(), parent.getId(), issueLinkType.getId(), 0L, getCurrentUser());
    updateIssue(issue);
}

private ApplicationUser getCurrentUser() {
    JiraAuthenticationContext authenticationContext = ComponentAccessor.getJiraAuthenticationContext();
    return authenticationContext.getLoggedInUser();
}

private IssueLinkType getIssueLinkType(String issueLinkTypeName) {
    IssueLinkService issueLinkService = ComponentAccessor.getComponent(IssueLinkService.class);
    def issueLinkTypes = issueLinkService.getIssueLinkTypes()
    logger.debug("issueLinkTypes ${issueLinkTypes}");
    IssueLinkType issueLinkTypeRealizes = issueLinkTypes.find { it.name == issueLinkTypeName };
    return issueLinkTypeRealizes;
}

List<IssueLink> getIssueLinks(Issue issue, String linkName, String linkDirection) {
    IssueLinkManager issueLinkManager = ComponentAccessor.getIssueLinkManager();
    List<IssueLink> links = new ArrayList<>();
    if (linkDirection == LINK_DIRECTION_INWARD) {
        links.addAll(issueLinkManager.getInwardLinks(issue.getId()));
    } else if (linkDirection == LINK_DIRECTION_OUTWARD) {
        links.addAll(issueLinkManager.getOutwardLinks(issue.getId()));
    }

    List<IssueLink> filteredLinks = links.findAll { it.getIssueLinkType().getName() == linkName }
    logger.debug("found ${filteredLinks.size()} issueLinks");
    return filteredLinks;
}

Set<Issue> getIssuesFromLinks(List<IssueLink> issueLinks, String linkDirection) {
    Set<Issue> issues = new HashSet<>();
    for (IssueLink link : issueLinks) {
        logger.debug(" dest ${link.getDestinationObject().getKey()} source ${link.getSourceObject().getKey()}")
        if (linkDirection == LINK_DIRECTION_INWARD) {
            issues.add(link.getSourceObject());
        } else if (linkDirection == LINK_DIRECTION_OUTWARD) {
            issues.add(link.getDestinationObject());
        }
    }
    return issues;
}

void updateIssue(Issue issue) {
    JiraAuthenticationContext authenticationContext = ComponentAccessor.getJiraAuthenticationContext();
    ApplicationUser user = authenticationContext.getLoggedInUser();
    IssueManager issueManager = (IssueManager) ComponentAccessor.getComponent(IssueManager.class);
    logger.debug("throw Issue Updated Event for issue ${issue.key}")
    issueManager.updateIssue(user, (MutableIssue) issue, EventDispatchOption.ISSUE_UPDATED, false);
}

Step 3

Sometimes it is necessary to start a re-index of Jira so that the changes can be seen.

Please check with another JQL query if the number of changed epics corresponds to the result of the first query before the script was executed.

issueFunction in hasLinkType("Epic-Story Link") AND issuetype = Epic AND issueLinkType in ("Parent of")

Open a couple of the Jira Epics and make sure that the link was inserted correctly.

The linked issues with the 'Issues in Epic' link should now also be available as a 'Parent of' link. Verify that all issues that were previously linked to the ART issue with the Jira Epic Link are now additionally linked using the Parent of Link.

Step 4

You now have two options to change the issue type of the Jira Epics to a desired issue type:

  • Change the issue type to an issue type of your choice via Jira's 'Bulk Change' functionality.

OR

  • Change the Issue Type Scheme in the ART project to the 'Agile Hive - Program - Issue Type Scheme' and follow the instructions of the wizard.

With the change of the issue type, the 'Issues in Epic' links disappear. (Important: This step cannot be undone!)

OR

Done

You have now successfully exchanged your Jira epics with SAFe-compliant issue types and set the hierarchical link to child issues.


Convert Issue Link Types to any other Link Type

As described in the previous step, issues that are in a hierarchical relationship to each other must use the Agile Hive Link (Parent of / Child of). We provide a script with which you can change all link types of desired issues in bulk.

There are four types of Agile Hive links in total for different tasks:

(1) Agile Hive Link

  • This link type links issues hierarchically, that are located on adjacent layers (layers / SAFe levels cannot currently be skipped).
  • It consists of the two link directions "Parent of" and "Child of".
  • Purpose: Aggregation of progress and statistics for all reports.

(2) Agile Hive Objective Link

  • This link type links Team Objectives to other planned issues of the same team.
  • You have to link an objective with at least one planned story so that the objective can be seen in the respective PI in the reports (this will be improved soon).
  • It consists of the two link directions "Belongs to Objective" and "Is Objective of".
  • Purpose: Summation of the story points that contribute to the respective objective in the Team Report as well as progress display based on the completed story points.

(3) Agile Hive Risk Link

  • This link type links Risks to other issues, that will mitigate the risk.
  • It consists of the two link directions "Treats" and "Is treated by".
  • Purpose: Issues that mitigate a risk are automatically displayed in the Team / Program / Solution Reports.

(4) Agile Hive Dependency Link

  • This link type links issues to dependent issues.
  • It consists of the two link directions "requires" and "is required by".
  • Purpose: Visual dependencies in Program & Breakout Boards.

Step 1

Install ScriptRunner for Jira and open the ScriptRunner Script Console (Jira Administration → Manage Apps → Scriptrunner → Script Console).


Step 2

Insert the script content on the right side into the Script Console.

  • Line 29 - New link type
    • Replace "Agile Hive Objective Link" with the name of the desired link type.
  • Line 32 - JQL
    • Adjust the JQL to your needs. All issues which are found by this JQL will be affected.
  • Line 35 - Old link type that will be replaced by the new one
    • Replace "Objective" with the name of the link type, that should be replaced by the new one.

Note: First test the script with only one issue. To do this, adjust the JQL in Line 32.

Execute the script via the "Run" button at the bottom.

Sometimes it is necessary to start a re-index of Jira so that the changes can be seen.

Change Link Type Script

New Script (documentation not yet available)

Done

You have successfully converted the issue links.


Change link directions

Sometimes you may want to change the link direction of a specific link type for specific issues. This sections quides you through the process.

Step 1

Install ScriptRunner for Jira and open the ScriptRunner Script Console (Jira Administration → Manage Apps → Scriptrunner → Script Console).


Step 2

Insert the script content on the right side into the Script Console.

  • Line 27 - Link type
    • Replace "Agile Hive Objective Link" with the name of the desired link type.
  • Line 30 - Link direction 
    • Specify which direction should be changed. Enter OUTWARD or INWARD.
  • Line 33 - JQL
    • Adjust the JQL to your needs. All issues which are found by this JQL will be affected. Therefore it is essential, that only issues of the specified link direction in line 30 appear in the search result.

Note: First test the script with only one issue. To do this, adjust the JQL in Line 33.

Execute the script via the "Run" button at the bottom.

Sometimes it is necessary to start a re-index of Jira so that the changes can be seen.

Change Link Direction Script

Done

You have successfully swapped the link direction.



 

3. Required Project Configuration

This table shows which issue types, fields, workflow statuses etc. are technically required. Please add those to the schemes of your existing projects. 

We strongly encourage you to look at the pre-made Agile Hive Schemes to familiarize yourself with the recommended and SAFe compliant configuration.

Technically requiredImportant notes

SAFe Layer

Portfolio

Large Solution

Program

Team

Issue Types

Agile Hive does not use Jira Epics because they cannot be brought into line with the SAFe methodology and nomenclature. You need to migrate them to other issuetypes:

Migrate Jira Epics

  • -
  • Objective
  • Risk
  • Objective
  • Risk
  • Objective
  • Risk
Fields

Default Portfolio Screen

  • Epic Owner
  • User-business Value
  • Time Criticality
  • RROE
  • Cost of Delay
  • Job Size
  • WSJF

Default Solution Screen

  • User-business Value
  • Time Criticality
  • RROE
  • Cost of Delay
  • Job Size
  • WSJF


Risk Screen

  • Impact
  • Probability
  • Residual Impact
  • Residual Probability
  • Residual Exposure
  • Exposure

Default Program Screen

  • Program Increment
  • Teams Involved
  • User-business Value
  • Time Criticality
  • RROE
  • Cost of Delay
  • Job Size
  • WSJF
  • Planned Start Date
  • Planned End Date


Risk Screen

  • Impact
  • Probability
  • Residual Impact
  • Residual Probability
  • Residual Exposure
  • Exposure

Default Team Screen

  • Program Increment


Team Objective Screen

  • Plan Business Value
  • Actual Business Value
  • Uncommitted Objective


Risk Screen

  • Impact
  • Probability
  • Residual Impact
  • Residual Probability
  • Residual Exposure
  • Exposure
Workflow Statuses
  • -
  • -
  • Program Backlog
  • -
Permissions

Please read our best practice article on permissions:

Set Up Permissions

Every user needs:

  • Browse Projects
  • Link Issues

Every user needs:

  • Browse Projects
  • Link Issues

Every user needs:

  • Browse Projects
  • Link Issues

Every user needs:

  • Browse Projects
  • Link Issues
Board
  • -
  • -
  • -
  • Scrum
  • Make sure to select the 'Primary board' of the team in the project configuration, after the project has been added to the Agile Hive Project Hierarchies:


Permission Scheme

In principle, you can freely configure the permission schemes that you use for Agile Hive projects.
With the following best practice, we ensure, among other things, that all users within a Hive can

  • see all projects and their issues (which is a must to view correct Agile Hive reports and other views).
  • link all issues with each other.
  • create issues in every project.
  • comment on all issues.
  • upload attachments in all issues.

To do so please follow these steps:

  1. Create a permission scheme for Agile Hive (call it for example 'Agile Hive Permission Scheme') and use it for all of your Agile Hive projects.
  2. Create a group (call it for example 'Agile Hive 1 - All Users') for all users who work together within a Hive and add the corresponding users to it.
  3. Grant this group the following permissions in the Agile Hive Permission Scheme:
    1. Browse Projects (must)
    2. View Development Tools
    3. View Read-Only Workflow
    4. Assignable User
    5. Assign Issues
    6. Create Issues
    7. Link Issues (must)
    8. View Voters and Watchers
    9. Add Comments
    10. Delete Own Comments
    11. Edit Own Comments
    12. Create Attachments
    13. Delete Own Attachments
    14. Delete Own Worklogs
    15. Edit Own Worklogs

All other settings are project-specific. We recommend that there is at least one project administrator in every project so that the permissions do not have to be configured by Jira administrators in the future, but rather directly from the teams, for example.

Example for the Team Level

Permission

Granted to

Project permissions

Administer Projects

Project role

  • Project Administrator
Browse Projects

Group

  • Agile Hive 1 - All Users
Edit Sprints

Single user

  • All team members
Manage Sprints

Single user

  • name (RTE)
  • All team members
Start/Complete Sprints

Single user

  • All team members
View Development Tools

Group

  • Agile Hive 1 - All Users
View Read-Only Workflow

Group

  • Agile Hive 1 - All Users

Issue permissions

Assignable User

Group

  • Agile Hive 1 - All Users
Assign Issues

Group

  • Agile Hive 1 - All Users
Close Issues

Single user

  • All team members
Create Issues

Group

  • Agile Hive 1 - All Users
Delete Issues

Project role

  • Project Administrator
Edit Issues

Single user

  • All team members
Link Issues

Group

  • Agile Hive 1 - All Users
Modify Reporter

Project role

  • Project Administrator
Move Issues

Project role

  • Project Administrator
Resolve Issues

Single user

  • All team members
Schedule Issues

Single user

  • All team members
Set Issue Security-
Transition Issues

Single user

  • All team members

Voters & watchers permissions

Manage Watchers

Project role

  • Project Administrator
View Voters and Watchers

Group

  • Agile Hive 1 - All Users

Comments permissions

Add Comments

Group

  • Agile Hive 1 - All Users
Delete All Comments

Project role

  • Project Administrator
Delete Own Comments

Group

  • Agile Hive 1 - All Users
Edit All Comments

Project role

  • Project Administrator
Edit Own Comments

Group

  • Agile Hive 1 - All Users

Attachments permissions

Create Attachments

Group

  • Agile Hive 1 - All Users
Delete All Attachments

Project role

  • Project Administrator
Delete Own Attachments

Group

  • Agile Hive 1 - All Users

Time tracking permissions

Delete All Worklogs

Project role

  • Project Administrator
Delete Own Worklogs

Group

  • Agile Hive 1 - All Users
Edit All Worklogs

Project role

  • Project Administrator
Edit Own Worklogs

Group

  • Agile Hive 1 - All Users
Work On Issues

Single user

  • All team members
  • No labels
This page was last edited on 06/26/2023.