Sync Agents: Automate Jira Portfolio Hierarchy Building
Sync Agents automatically populate and maintain Foundation Lenses using JQL queries and relationship rules — no manual issue-by-issue assembly. JQL Insert pulls matching issues. Child Extend pulls children under them. Agents stay fresh automatically via Jira event triggers.
What is a Sync Agent?
A Sync Agent is a rule that automatically brings Jira issues into a Lens. Instead of adding issues one-by-one, you point the agent at a JQL query or a parent relationship, and Foundation pulls the matching work into the tree and keeps it up to date as Jira changes. Most portfolio Lenses use one or two agents to build the top of the hierarchy — every Epic in a program, for instance — then manual drag-and-drop or Flex Items to organize the rest. Agents run in a fixed pipeline order (Insert → Extend → Filter → Group → Sort), so you never have to think about dependencies between them. See the full Sync Agents overview in the docs.
What types of Sync Agents does Foundation have?
Three types in MVP — JQL Insert, Child Extend, and Linked Items Extend — with more on the roadmap.
| Type | What it does | Status |
|---|---|---|
| JQL Insert | Runs any JQL query and inserts every match under a parent. | MVP |
| Child Extend | Walks Jira parent/child links and pulls children into the tree. | MVP |
| Linked Items Extend | Follows issue links (blocks, relates to, clones) from each node. | MVP |
| Hierarchy Builder | Reconstructs full multi-level hierarchy from a flat JQL result. | Post-MVP |
| Filter / Group / Sort | Shape the tree after Insert and Extend run. | Post-MVP |
| JPD Links | Pull delivery tickets linked to Jira Product Discovery ideas. | Roadmap |
How does JQL Insert work?
JQL Insert runs the JQL query you write against Jira, reads the full list of matching issues, and inserts them under a parent node in your Lens. Add the agent at the root and matches become top-level rows; add it under a Flex Item and they become children of that folder. Foundation validates the JQL on save using Jira's own validator, so syntax errors surface inline — no "wait 30 seconds, then error." You set a Max Items cap (default 1,000), and the agent runs respecting the Lens owner's Jira BROWSE permissions. The result appears in seconds for small queries and as a background job for larger ones. See JQL Insert agent for step-by-step configuration and Atlassian's JQL reference for query syntax.
How does Child Extend work?
Child Extend walks Jira's parent/child relationship for every issue already in its parent subtree and pulls each issue's children in. Pair it with a JQL Insert to build the classic Epic → Story → Sub-task tree with two agents total. You pick a depth — 1 for direct children only, 2 for children and grandchildren, rarely more. Because Sync Agents run in a fixed pipeline (Insert before Extend), adding Child Extend first in the UI still works: the pipeline reorders them automatically. For issue links instead of parent/child, reach for Linked Items Extend. Detailed configuration lives on the Child Extend agent doc page.
How do Sync Agents stay fresh without polling Jira?
Foundation subscribes to Jira's product event stream — avi:jira:created:issue, avi:jira:updated:issue, avi:jira:deleted:issue — through Forge. When an issue changes in Jira, Atlassian pushes the event to Foundation within seconds. We then re-evaluate the affected Sync Agents, fetch the one issue that changed, update the local cache, and publish a Realtime message to any connected Lens clients. The events are free — they do not draw from your Jira API rate-limit budget — and they fire only when real changes happen, not on a fixed poll interval. A periodic safety-net check catches the rare edge case where an event was missed. See Run & schedule agents for the full refresh model.
How do Sync Agents differ from Structure's generators?
Same intent, different execution. Structure calls these generators and they run on a fixed polling schedule — the generator executes every few minutes against Jira to pick up changes. That works, but every poll costs Jira API points even when nothing has changed, which matters under Atlassian's March 2026 rate-limit enforcement. Foundation's Sync Agents are push-based: we wait for Jira to tell us something changed, then react. Net result on a typical portfolio: Foundation uses roughly an order of magnitude fewer Jira API points per day than an equivalent Structure setup. See the full Foundation vs Structure comparison for the rate-limit math, pricing, and migration path.
Can I run Sync Agents on a schedule?
Yes, but you rarely need to. The default behavior is event-driven — agents re-run automatically whenever a relevant Jira issue is created, updated, or deleted. On top of that, Foundation runs agents when you open a Lens with stale data, and a periodic safety-net job catches any missed events. If you want to force a run — say, after editing a JQL query and wanting to see the result immediately — click Run Sync Agents in the Lens Inspector. Long runs execute as Forge async events with a 15-minute timeout and report status via a toast. True scheduled runs (fixed cadence, independent of events) are on the post-MVP roadmap; file a request if you have a use case.
Frequently asked questions
Do Sync Agents slow down Jira?
No. Sync Agents listen to Jira's free product event triggers (avi:jira:updated:issue and friends) — Forge pushes the events to Foundation the moment they fire in Jira, with no polling and no rate-limit cost for the event itself. Only the follow-up fetch of issue details costs points, and it only runs for the single issue that changed. Your Jira site experiences exactly zero Foundation-induced load during normal operation.
Can I disable a Sync Agent temporarily?
Yes. Every Sync Agent has an enable/disable toggle in the Lens Inspector panel. Disabled agents stop running immediately but retain their configuration so you can re-enable later. You can also delete an agent outright — Foundation keeps the issues the agent inserted (they become manual rows) unless you explicitly choose to remove them.
What happens if my JQL returns 10,000 issues?
Foundation enforces a default Max Items cap of 1,000 per agent and a hard Lens cap of 10,000 rows (including Flex Items and children pulled by other agents). If your query returns more than the cap, the first N matches are inserted in Jira's ordering and a warning appears in the Sync Agents panel telling you to tighten the JQL. In practice, writing JQL that scopes to "unresolved in the last 180 days" solves this for most portfolio use cases.
Can I use custom fields in Sync Agent JQL?
Yes. Any JQL your Jira site supports works in a Sync Agent — custom fields, cf[10042], scriptrunner functions (if your site has ScriptRunner), epic link filters, and sprint functions. Foundation validates the JQL on save and shows a red error inline if it fails. If a custom field is not returned by Jira's metadata API for the caller, the agent still runs but the field will not appear as a column until an admin exposes it.
How do I debug a Sync Agent that is not pulling expected issues?
Open the Lens Inspector and find the Sync Agents section. Each agent shows its last run time, the number of issues inserted, and any errors or warnings from the most recent execution. Click the agent to see its configuration and the underlying JQL. If issues are missing, the three most common causes are: the lens owner lacks Jira BROWSE permission on those issues, the JQL is wider than you think and hit the Max Items cap, or the issues sit outside the agent's parent node in the Lens hierarchy.