Project Groups for Jira

1. Overview
2. Installation
3. Group Editor
4. Group as a project setting
5. Browsing projects by groups
6. Browsing projects by lead
7. Settings
8. Workflow condition
9. JQL Functions
10. Project console
11. Using project groups in reports
12. APIs
13. Troubleshooting

1. Overview

Project Groups for JIRA extends your Jira instance with the following features:

Combining projects into groups with a multi-level hierarchy and browsing projects by these groups.
JQL functions to search issues in projects in specified groups.
A workflow condition to make sure transitioned issue is in the project within the specified groups.
Browse projects by lead.
The Project Console, which allows you to bulk change some project settings.
REST API to automate and integrate grouping functionality with your favorite business tools.

2. Installation

Install the app via the Atlassian Marketplace or follow the standard installation process through the UPM.

Immediately after installing and applying the license key, you can browse projects by lead, use the Project Console, or create project groups in the Group Editor.

3. Group Editor

You must have the JIRA System Administrators global permission to access Group Editor.

Choose: Cog → Projects → Project groups (sidebar)

The group editor consists of three columns. The left column contains a tree of project groups, the middle column contains a list of projects in the currently selected group, and the right column (Ungrouped projects) contains a list of projects that are not currently included in any group.

3.1 Creating a group

3.1.1 Import from project categories

In some cases, a good way to get start is to import project categories as groups. To do this on a fresh install, click "Import from categories" button in the groups area, or click the dots next to the Add Group button and select "Import from categories".

You can do this at any time, but be aware that importing categories will remove any existing groups (if any).

3.1.2 Creating a group manually

Create some groups by clicking the Add Group button. You can add a subgroup to an existing group by selecting the parent group in the create modal. Or you can add a subgroup by clicking on the dots next to the group name and then selecting the Add subgroup option. You can create any number of groups with any nesting level. The only limitation is that groups on same level must have different names.

3.2 Project management

To add a project to a group, select the group and drag the project from the Ungrouped projects column to the middle one. Or you can drag the project from the Ungrouped projects or middle column directly to the desired group in the left column. The latter allows you to quickly move a project from one (selected) group to another.

In addition to the Group Editor, there are two more ways to associate a project with a group: using the project settings and using the Project Console.

To remove a project from a group, drag it to the Ungrouped Projects column.

The number badge next to the group name shows the number of projects currently in that group.

3.3 Editing a group

You can edit the group name or move it to another group by clicking on the dots next to the group name and then selecting the Edit group option.

To move a group to the top level, click the cross icon on the right side of the parent group field, this will clear the field.

3.4 Deleting a group

To delete a group, click on the dots next to the group name and then select the Delete Group option. If the group to be deleted contains subgroups, they will also be deleted, i.e. you always delete the whole branch. All projects from deleted groups are moved to the Ungrouped Projects column.

3.5 Importing and exporting groups

You can export and then import all project group data in the YAML format.

All Project Groups app data is backed up during a standard Jira database backup. So if you're moving data to another Jira instance, for example, you don't need to do a YAML export.

To export data, click the dots next to the Add Group button and select Export to YAML. After that, a yaml format file will be downloaded, containing data on the structure of groups and linking projects to groups.

To import data, click the dots next to the Add Group button and select Import from YAML.

Of course, since YAML is just text, you can create your own file from scratch. Sometimes this is the fastest way to create a group structure and link projects. Our yaml format is quite simple. Here's an example:

projectGroups:
- name: Group 1
  projects: [PROJECTKEY1, PROJECTKEY2, PROJECTKEY3]
  subgroups: []
- name: Group 2
  projects: [PROJECTKEY4]
  subgroups:
  - name: Subgroup 1
    projects: [PROJECTKEY5, PROJECTKEY6, PROJECTKEY7, PROJECTKEY8]
    subgroups: []
  - name: Subgroup 2
    projects: [PROJECTKEY9, PROJECTKEY10]
    subgroups: []

yaml

4. Group as a project setting

You must have the JIRA System Administrators global permission to change project settings.

Go to the project settings page and on the left sidebar, find the "Group" link. On the page that opens, you can select a group for the current project.

5. Browsing projects by groups

Choose: Projects (top menu bar) → Browse By Group

On a left sidebar is a hierarchical groups list, and links to all and ungrouped projects. Number near group name is a number of projects in current group (excluding projects in subgroups).

Click on "Subgroups" toggle (default is on) to view projects only in current group, without subgroups.

6. Browsing projects by lead

Choose: Projects (top menu bar) → Browse By Lead

If current user is lead of at least one project, then list of his projects will open automatically.

7. Settings

Choose: Cog → Manage apps → Settings (left menu, Project Groups section)

Three settings available:

Enable Project Browser by Group	If enabled, users will see a Browse By Group option in the Projects menu in the main horizontal navigation bar at the top of your screen.
Enable Project Browser by Lead	If enabled, users will see a Browse By Lead option in the Projects menu in the main horizontal navigation bar at the top of your screen.
Allow project administrators to associate projects with groups	If enabled, then users with the Administer Projects permission will see the Group item in the menu on the project settings page and will be able to create or change the project's association with the group. If disabled, the Group item will only be visible to users with JIRA Administrators or JIRA System Administrators global permission.

8. Workflow condition

Plugin provides workflow "Project Group Condition" that allows you to perform transition based on project is included/not included in specified project groups.

9. JQL Functions

9.1 projectGroups()

Plugin provides JQL function projectGroups() that allows you to search issues based on project is included in specified groups.

project in projectGroups("Design")

You can provide multiple groups:

project in projectGroups("Design", "Development")

Please note that if you have several groups with same title, function will return all projects in all groups with that title.

9.2 projectGroupsHierarchy()

projectGroupsHierarchy() works similarly to projectGroups(), except that it returns issues in the projects of the specified group, as well as all of its subgroups at all levels.

10. Project console

Choose: Cog → Projects → Project console (sidebar)

10.1 Columns customization

You can change which columns is displayed in projects table with «Columns» button in upper right corner. Columns set is saved for current user. Project key with link to project page is always visible, as a cog icon with link to project administration page.

10.2 Projects filtering

You can filter projects by visible columns. Use drop-down lists at the top of table for this. Buttons with lists containing changed values are marked green.

10.3 Bulk changing projects settings

Regardless of filter active or not, you can use «Bulk Edit» button for bulk change projects settings. If filter is active, you’ll see only filtered projects. At the moment you can edit following settings:

Group
Category
Permission Scheme
Screen Scheme
Field Layout Scheme
Notification Scheme

11. Using project groups in reports

The easiest way to use project group data in reports is if your reporting tool makes direct requests against the Jira database. Project Groups for Jira use two database tables to store group-related data - AO_2E9800_GROUPS and AO_2E9800_PROJECT_LINK:

create table "AO_2E9800_GROUPS"
        (
            "ID"          serial primary key,
            "PARENT_ID"   integer default 0,
            "TITLE"       varchar(255),
            "BREADCRUMBS" varchar(255),
        );

sql

create table "AO_2E9800_PROJECT_LINK"
        (
            "ID"         serial primary key,
            "GROUP_ID"   integer default 0,
            "PROJECT_ID" bigint  default 0
        );

sql

An example query giving an idea of how to get the project group of an issue:

select issue.id, "group"."BREADCRUMBS"
        from jiraissue issue
                 join
             "AO_2E9800_PROJECT_LINK" project_link on issue.project = project_link."PROJECT_ID"
                 join
             "AO_2E9800_GROUPS" "group" on project_link."GROUP_ID" = "group"."ID"

sql

12. APIs

Use APIs to automate and integrate with your favorite business tools.

13. Troubleshooting

See our Troubleshooting guide.