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:
Scenario 1 - The ART and its teams each have their own projects
Step 1Add the ART and the team projects into the correct layers of the Agile Hive Project Hierarchies and set up the relationship between them. | |
Step 2Make 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. | |
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 1Create a new project for each team by using the 'SAFe Team Project' Template. | |
Step 2Move the team level issues (like stories etc.) into the corresponding team project by using JQL and the move functionality of Jira. | |
Step 3Add the ART and the team projects into the correct layers of the Agile Hive Project Hierarchies and set up the relationship between them. | |
DoneYou 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. |
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 1Install ScriptRunner for Jira and open the ScriptRunner Script Console (Jira Administration → Manage Apps → ScriptRunner → Script Console). | |
Step 2Please first check with a JQL query the number of Epics that need to be changed and save the result.
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 |
Step 3Sometimes 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.
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 4You now have two options to change the issue type of the Jira Epics to a desired issue type:
OR
With the change of the issue type, the 'Issues in Epic' links disappear. (Important: This step cannot be undone!) | OR |
DoneYou 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 1Install ScriptRunner for Jira and open the ScriptRunner Script Console (Jira Administration → Manage Apps → Scriptrunner → Script Console). | |
Step 2Insert the script content on the right side into the Script Console.
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) |
DoneYou 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 1Install ScriptRunner for Jira and open the ScriptRunner Script Console (Jira Administration → Manage Apps → Scriptrunner → Script Console). | |
Step 2Insert the script content on the right side into the Script Console.
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 |
DoneYou have successfully swapped the link direction. |
3. Required Project Configuration
This table shows which issue types, fields, workflows 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.
General: Deleted issue types, workflows, custom fields and other entities are automatically recreated by Agile Hive in the following cases:
- Create a new project using one of our Agile Hive templates (e.g. “SAFe ART Project” or “SAFe Scrum Team Project”)
- Manual recalculation
- Update of Agile Hive
- Re-installation of Agile Hive after it has previously been uninstalled
- Re-activation of Agile Hive after it was previously deactivated
- Restart of Jira
Technically required | Important notes | SAFe Layer | |||
---|---|---|---|---|---|
Portfolio | Large Solution | ART | 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: |
|
|
|
|
Fields | Default Portfolio Screen
Milestone Screen
| Default Solution Screen
Milestone Screen
Risk Screen
| Default ART Screen
Milestone Screen
Risk Screen
ART Objective Screen
| Default Team Screen
Risk Screen
Team Objective Screen
| |
Workflows | You can use your own workflows or adapt those from Agile Hive. Important: Please do not rename the workflows provided by Agile Hive. (Unlike other entities in Jira, workflows do not have an internal ID. We therefore use the names of the workflows for identification.) |
|
|
|
|
Permissions | Please read our best practice article on permissions: | Every user needs:
| Every user needs:
| Every user needs:
| Every user needs:
|
Board |
|
|
|
|
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:
- 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.
- 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.
- Grant this group the following permissions in the Agile Hive Permission Scheme:
- Browse Projects (must)
- View Development Tools
- View Read-Only Workflow
- Assignable User
- Assign Issues
- Create Issues
- Link Issues (must)
- View Voters and Watchers
- Add Comments
- Delete Own Comments
- Edit Own Comments
- Create Attachments
- Delete Own Attachments
- Delete Own Worklogs
- 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
|
Browse Projects | Group
|
Edit Sprints | Single user
|
Manage Sprints | Single user
|
Start/Complete Sprints | Single user
|
View Development Tools | Group
|
View Read-Only Workflow | Group
|
Issue permissions | |
Assignable User | Group
|
Assign Issues | Group
|
Close Issues | Single user
|
Create Issues | Group
|
Delete Issues | Project role
|
Edit Issues | Single user
|
Link Issues | Group
|
Modify Reporter | Project role
|
Move Issues | Project role
|
Resolve Issues | Single user
|
Schedule Issues | Single user
|
Set Issue Security | - |
Transition Issues | Single user
|
Voters & watchers permissions | |
Manage Watchers | Project role
|
View Voters and Watchers | Group
|
Comments permissions | |
Add Comments | Group
|
Delete All Comments | Project role
|
Delete Own Comments | Group
|
Edit All Comments | Project role
|
Edit Own Comments | Group
|
Attachments permissions | |
Create Attachments | Group
|
Delete All Attachments | Project role
|
Delete Own Attachments | Group
|
Time tracking permissions | |
Delete All Worklogs | Project role
|
Delete Own Worklogs | Group
|
Edit All Worklogs | Project role
|
Edit Own Worklogs | Group
|
Work On Issues | Single user
|