Skip to content
Foundation Docs

JQL Insert agent

A JQL Insert Sync Agent runs a JQL query against Jira and inserts every matching issue under a parent node in your lens. Use it when you want a lens that tracks “all Epics in project Acme” or “everything my team owns that’s unresolved” without adding issues by hand.

Add a JQL Insert agent

Section titled “Add a JQL Insert agent”
  1. Open the lens you want to populate and open the Inspector panel.
  2. In the Sync Agents section, click Add Sync Agent.
  3. From the Type dropdown, pick JQL Insert.
  4. Enter your query in the JQL field. For example: 
    project = ACME AND issuetype = Epic AND resolution = Unresolved
  5. Foundation validates the JQL on blur and shows a red error if anything is off.
  6. Set Max items (default 1000, up to the 10,000-row lens limit).
  7. Click Save.

The agent runs immediately and the matching issues appear under the parent node. A progress toast tracks long-running jobs.

Where it inserts

Section titled “Where it inserts”
  • If you add the agent at the root, matching issues are inserted as top-level nodes in the lens.
  • If you add it under a Flex Item, the issues are inserted as children of that folder.
  • You can’t nest a Sync Agent under an issue node that was itself created by a Sync Agent.

Writing good JQL

Section titled “Writing good JQL”
  • Start narrow. A query returning 5,000 issues will cost Jira API points to resolve — keep the scope to what you actually want to see.
  • Filter by resolution = Unresolved or a date window (updated >= -180d) to avoid dragging in years of old issues.
  • Use Jira’s JQL editor to test the query first, then paste it in.

What counts as a match

Section titled “What counts as a match”

The agent pulls every issue the query returns, respecting the lens owner’s Jira BROWSE permissions. If a viewer can’t see an issue in Jira, Foundation hides that row for them.

Section titled “Related”