Grouping Jira Issues by Custom Hierarchy

Jira's native grouping stops at Epic, Sprint, and assignee. It has no concept of “portfolio,” “fiscal quarter,” or “OKR” as a grouping dimension. Foundation Flex Items plus Sync Agents build arbitrary groupings above the issue layer, cross-project, without touching Jira's schema — so you can group by whatever dimension your organization actually plans against.

What does “custom grouping” mean in a Jira context?

Custom grouping means organizing a flat list of Jira issues under arbitrary parent buckets that don't exist in the Jira data model itself. The buckets might be portfolios, fiscal quarters, OKRs, strategic themes, business units, or customer segments. The issues underneath are real Jira issues from one or many projects. The grouping is a view-time construct — it lives in the tool that renders the hierarchy, not in Jira's schema.

This matters because most planning conversations happen at the grouping layer, not at the issue layer. “How is the Growth portfolio tracking?” is a grouping question. “Is FY26-Q2 on plan?” is a grouping question. Jira's issue list answers neither of those directly — you have to roll up underneath a bucket that the issue list doesn't know how to express.

What grouping does native Jira already do (and where does it stop)?

Native Jira supports a handful of groupings, and they cover a surprising number of day-to-day cases before running out. Board views group by Epic, Sprint, or assignee. The Backlog groups by Sprint (active, future, backlog). JQL queries built with advanced search can sort and filter by any field, including custom single-select fields, but JQL has no “group by” clause — it returns a flat list.

Three walls show up quickly when you push on native grouping. First, grouping stops at the project boundary — a board-level Group By runs only against that board's configured filter, and most boards are single-project. Second, you can only group by one dimension at a time; stacking “Portfolio then Team then Epic” is not possible in native views. Third, grouping by labels is technically available but gives you no rollup semantics — labels are flat strings, so you can filter to a label but you can't see a parent row that totals child story points.

How does Structure's Group Generator build grouping?

Structure by Tempo solves custom grouping with a feature called a Group Generator. You configure a generator that takes a source set of issues (from JQL) and a grouping field (a custom select, a component, a version, whatever), and Structure inserts one synthetic parent row per distinct value. Children are the matching issues.

Group Generators are powerful — you can stack multiple generators to get nested groupings (Portfolio > Team > Epic), and they update when the underlying source set changes. The tradeoffs are the same as the rest of Structure: a steep learning curve (the generator editor is deep), a separate data layer outside Jira for the generated hierarchy, and a pricing model that adds up alongside Structure.Gantt if you need both.

How does Foundation use Flex Items + Sync Agents to group issues?

Foundation splits grouping into two composable primitives. Flex Items are hierarchy nodes that aren't Jira issues — they represent a group, portfolio, quarter, or OKR. You create them directly in a Lens. They accept children just like any parent row and they roll up child totals (story points, progress, dates) without any schema change in Jira. Sync Agents are JQL-driven attachment rules. Each agent runs a query and attaches matching issues under the Flex Item (or another parent) it's bound to.

The mental model is: Flex Items define the groups, Sync Agents populate the groups. Because Sync Agents are JQL, the grouping dimension can be anything you can express in JQL — a custom field, a component, a label, a combination of those, or even a date window. And because JQL is cross-project by default, your grouping spans all projects the user has BROWSE permission on.

Refresh is event-driven. Foundation listens to Jira product events (free, no rate-limit cost), so when an issue's Team field changes from Alpha to Beta, it moves under the right Flex Item on the next Lens load without a manual rerun. This is different from CSV-exported or dashboard-based groupings, which go stale the moment fields change.

Step-by-step — a Foundation group-by setup

The five-step flow below builds a portfolio-by-team grouping across three projects. Total time is about 45 minutes for a first-time setup; subsequent Lenses are faster because you reuse the pattern.

Create a Foundation Lens. Open Foundation from the Jira Apps menu and create a new Lens. Name it after the grouping dimension — for example “FY26 Portfolio Rollup” or “Team-by-OKR.” The Lens is the container, empty at first.
Add top-level Flex Items for each group. Inside the Lens, add one Flex Item per group you want to appear as a parent row. For a portfolio view, that's one Flex Item per portfolio. For a fiscal quarter view, one per quarter. Flex Items live above the Jira issue layer and require no schema changes in Jira.
Attach a Sync Agent (JQL) to each Flex Item. Under each Flex Item, add a JQL Insert Sync Agent. Write JQL that selects exactly the issues for that group — for example, project in (ALPHA, BETA) AND cf[10031] = Portfolio-A for a portfolio grouping that reads a custom field. The agent resolves the query and attaches matching issues as children.
Run generators and verify membership. Click Run Generators. The Lens now shows each Flex Item as an expandable parent with its Jira issues underneath. Check that no issue appears twice and that every issue you expect is under the right group. JQL typos are the most common failure.
Save as a view and share with permissions. Save the current column layout and grouping as a named View. Grant edit or view permission to the people who need access. The view updates automatically when Jira fields change.

How do you handle issues that belong to multiple groups?

Real portfolios have overlap. A platform-infrastructure story might serve both the Growth portfolio and the Retention portfolio. A cross-team initiative might count toward Team Alpha's OKR and Team Beta's OKR. Native Jira doesn't handle multi-membership well — an issue has one Epic, one Sprint, one assignee.

Foundation offers two patterns. Duplication: the same Jira issue appears under multiple Flex Items because multiple Sync Agents' JQL queries match it. This is transparent but can inflate rollup totals if you're summing story points across the whole Lens. Foundation shows a duplicate indicator on the row to make this visible. Primary + reference: pick one group as the issue's primary home and use a reference-only appearance under the other groups. The rollup counts the issue once, but it's still visible in context for cross-portfolio planning.

Which pattern to pick depends on what you're reporting. If the Lens answers “what is each portfolio delivering?”, duplication is fine because totals are per-portfolio. If the Lens answers “what is total org output?”, primary + reference avoids double-counting.

When is grouping the wrong abstraction (and you actually need separate hierarchies)?

Grouping is a view-time construct. It's the right tool when the underlying issues are the same in every view, but different audiences want them organized differently. An engineering leader wants grouping by team; a product leader wants grouping by customer segment; a finance leader wants grouping by cost center. Same issues, three Lenses, three groupings.

Grouping is the wrong abstraction when the parent entities have their own meaningful attributes, lifecycle, or permissions. If “portfolio” has its own owner, budget, health status, executive sponsor, and approval process, then portfolios are first-class entities — not groups. They probably belong in a custom issue-type hierarchy above Epic, or in a separate layer entirely (OKRs in an OKR tool, portfolios in a PPM tool).

A useful heuristic: if you'd want to report on the parent without showing its children, the parent is an entity, not a group. Entities need a hierarchy. Groups need a view. See custom hierarchy levels in Jira without Premium for when to build above Epic, and Jira Plans vs Structure vs Foundation for a head-to-head on the tools that do each.

Where Foundation fits

Foundation's approach — Flex Items plus Sync Agents — is the lightest-weight way to add custom grouping to Jira in 2026 without changing the Jira schema or paying for Jira Premium. It's cross-project by default, refresh is event-driven within seconds, and views persist per Lens so each audience gets the grouping they need. For the broader context, see the pillar guide on Jira hierarchy beyond Epic.

Frequently asked questions

Can I group Jira issues by a custom field without a Marketplace app?

Partially. Inside a single project board, you can group by any single-select custom field (Team, Component, Priority) on the board view. What you cannot do natively is group across multiple projects, build a grouping that stacks two dimensions (Portfolio then Team), or persist a custom-grouped view across board filter changes. For those, you need Structure, BigPicture, or Foundation.

Does grouping by Epic count as custom grouping?

Epic grouping is native Jira grouping, not custom — it uses the built-in Epic Link / parent-link field. It only works within a single issue-type hierarchy and does not extend above Epic. If you need to group Epics themselves under a portfolio, quarter, or OKR, native Jira runs out and you need Flex Items or a generator-based approach.

What is a Flex Item and why not just use a Jira label?

A label is a string attached to an issue — it's flat and every issue can carry many of them. A Flex Item is a node in a hierarchy that can have children; you attach real Jira issues underneath it. The difference matters when you want totals to roll up (story points, progress bars) under a grouping layer, which labels cannot do because they have no container semantics.

Can Sync Agents pull issues from more than one project?

Yes. A Sync Agent runs a JQL query, and JQL is cross-project by default. One agent bound to a Flex Item can pull issues from any combination of projects the user has BROWSE permission on. The 1,000-issue Lens cap in the MVP applies to the total Lens, not per agent.

How often does grouping refresh when Jira issues change fields?

Foundation listens to Jira product events (avi:jira:updated:issue) and re-runs the grouping logic within seconds. If an issue's Team custom field changes from Alpha to Beta, it moves under the Beta Flex Item on the next Lens load. No manual refresh required, unlike CSV-imported groupings or static JQL filters saved in dashboards.

Is custom grouping the same as a custom issue-type hierarchy?

No, and confusing them is common. A custom issue-type hierarchy changes what kinds of issues can exist (Initiative > Epic > Story) and requires Jira Premium or a Marketplace app. Custom grouping organizes whatever issues you already have under arbitrary buckets at view time — no schema change. Most portfolio problems are grouping problems, not hierarchy problems.