Filter Hygiene for Jira — Documentation

Setup screenshots

Interface screenshots

Contents

• Quick Start / After Install
• Setup screenshots
• Interface screenshots
• Supported impact and coverage limits
• Permissions & Data
• Troubleshooting
• Security & Privacy
• FAQ
• Support

Supported Products

• Jira Software (Cloud)
• Jira Service Management (Cloud)
• Jira Work Management (Cloud)
• Works in both Company‑managed and Team‑managed projects

Permissions & Data

• Required scopes: read:jira-work, read:jira-user, write:jira-work, read:filter:jira, read:user:jira, read:group:jira, read:project:jira, read:project-role:jira, read:field:jira, read:jql:jira, read:board-scope.admin:jira-software, validate:jql:jira, write:filter:jira, delete:filter:jira, and storage:app
• Data handled: filter metadata, owner/share data, parsed JQL reference evidence, direct board relationships, duplicate grouping, cleanup queue entries, deletion status, and before/after summaries for supported owner/share/deletion actions
• Hosting: Built on Atlassian Forge (no external servers)
• Storage: Forge storage for preferences, Recent Activity, bounded hygiene snapshots, and operational counters

Installation

1. Install from the Atlassian Marketplace (Jira Cloud).
2. The app adds a Jira admin page: Filter Hygiene.
3. Open the page from Jira Settings → Apps → Filter Hygiene.

Quick Start

1. Open Filter Hygiene from Jira settings → Apps → Filter Hygiene.
2. Optionally enter search criteria:
   • Filter name: search by name (contains match)
   • Owner: filter by a specific owner
   • Visibility: filter by share scope (Any, Private, Project, Group, Global)
3. Click "Scan" to search one Jira result page matching your criteria, or "Full scan" to progressively retrieve the complete saved-filter corpus Jira makes accessible under the acting permissions.
4. Review Cleanup need, Change impact, Action readiness, JQL status, duplicate groups, visibility, owner, and coverage before adding filters to the cleanup queue or running a supported action.

Understanding Results

• Cleanup need: Uses only concrete sharing, ownership, JQL validity, exact duplicate, description, staleness, and context evidence. NO PRIORITY SIGNAL means only that the scan found no configured cleanup-priority reason; it is not a safety claim.
• Change impact: Starts as Not checked. Use Review impact to check direct Jira Software boards and incoming references from the accessible saved-filter corpus. Known relationships are named; incomplete or failed supported lookups remain unknown.
• Action readiness: Starts as Preflight required. It reflects whether the action-specific live checks are ready, blocked, or uncertain—not whether a filter merely looks old.
• Visibility: Shows the current share scope (Private, Project, Group, Global, or Mixed)
• Owner: The user who owns the filter
• JQL and duplicate signals: Shows whether Jira can validate the JQL and whether normalized query text matches other filters in the scan
• Filter link: Click the filter name to open it in Jira

Supported impact and coverage limits

Filter Hygiene adds evidence Jira's ordinary JQL/results view does not assemble into one cleanup decision:

• Direct Jira Software boards: the app uses Jira's saved-filter-to-board lookup. A returned board is named and explains that changing the JQL changes board/backlog results and board-specific reports; deleting the filter can remove its source query.
• Incoming saved-filter references: the app parses the accessible saved-filter corpus through Jira and resolves exact filter IDs or unambiguous exact names. Known references are named and block deletion.
• Unknown due to failure or partial access: permission-denied, partial pagination, ambiguous names, parser omissions, and failed supported lookups stay distinct and block deletion.
• Unavailable or unchecked: dashboard gadgets, JSM queues, standalone/non-board reports, automations, exports, subscriptions Jira does not return, and external consumers are not inferred.

Zero supported relationships is not proof that a filter is unused or safe to delete. Full scan means every filter Jira returns to the app under the acting permissions; it does not include inaccessible private filters.

Bulk Actions

Select reviewed filters using the checkboxes, then choose an action from the Actions dropdown. Owner/share actions accept a bounded selection; permanent deletion requires exactly one filter:

• Reassign Owner: Transfer ownership of selected filters to another user. Useful for offboarding or consolidating filter ownership.
• Make Private: Remove all sharing permissions from selected filters, making them visible only to their owners. Filters that are already private are automatically skipped.
• Remove Global Share: Remove only the global/logged-in share permissions while preserving project and group shares. Filters without global share are automatically skipped.
• Delete Filters: Permanently delete exactly one reviewed filter after repeated live impact preflight and typed DELETE confirmation. Deleted filters cannot be restored by Filter Hygiene.

All actions show a live read-only preflight with current Jira owner/share data, planned changes, blocked filters, warnings, and restore eligibility before execution. Deletion repeats the supported board and saved-filter-reference checks immediately before the write. Known references, incomplete supported coverage, or stale reviewed evidence block deletion. Unsupported dashboard, queue, standalone-report, automation, export, subscription, and external use still requires manual review.

Single Filter Actions

Click the "..." menu on any filter row to access quick actions:

• Open filter: View the filter in Jira
• Copy filter link: Copy the filter URL to clipboard
• Reassign owner: Change the filter's owner
• Make private: Remove all sharing (only shown if filter is not already private)
• Remove global share: Remove global share (only shown if filter has global share)
• Review impact and dependencies: Check direct boards, incoming saved-filter references, and explicit coverage limits
• Delete filter: Permanently delete one reviewed filter after repeated impact preflight and typed confirmation

Export to CSV

Export your scan results for reporting or offline analysis:

1. Run a scan with your desired criteria.
2. Click "Export CSV" in the results header.
3. A CSV file downloads with filter details including owner, visibility, share evidence, Cleanup need and reasons, JQL status, duplicate group, recommended action, known dependencies, source coverage, Action readiness, and corpus coverage. Dependency fields remain Not checked until Review impact runs.

Use the delete candidate report when planning irreversible cleanup. It includes safety notes, top candidates, and an embedded CSV for offline review.

Cleanup summary and Recent Activity

Filter Hygiene maintains a Recent Activity record for exports, owner changes, privacy changes, global-share removals, and undo attempts:

• Click "Recent Activity" to expand the audit log section.
• Each entry shows the action type, number of filters affected, actor, before/after owner or share summaries, per-filter status, success/failure counts, failure reasons, and timestamp.
• Use Recent Activity export CSV or Markdown for cleanup evidence.
• Use "Export summary" after a scan to generate a Markdown cleanup summary with criteria, concrete cleanup counts, corpus coverage, and review notes.

Best Practices

• Start with a focused scan for global/logged-in sharing, inactive ownership, invalid JQL, or exact duplicates—then review impact before ranking the next action.
• Review filter ownership regularly, especially after team changes or offboarding.
• Use CSV, cleanup summary, and Recent Activity exports to create periodic audit reports for compliance or management review.
• Test owner/share actions on a small selection and review preflight blockers plus exact-undo eligibility before applying them.
• Delete only one reviewed filter at a time. Review known boards and saved-filter references, keep unsupported relationships visible, type DELETE, and verify Jira no longer returns the filter.

Troubleshooting

I can't see certain filters

• Filter Hygiene respects Jira permissions. You can only see and modify filters you have access to.
• Enable the private-filter scan option when you expect admin-visible private filters.
• Private filter coverage still depends on what Jira returns for your administrator permissions and site configuration.

Actions fail with permission errors

• Jira only lets eligible users modify filter ownership, sharing settings, or deletion state. In many cases the filter owner must run a permission change, or ownership must be reassigned first.
• Review the preflight warnings and blocked-filter reasons before retrying.

Some filters show as "already in desired state"

• This is expected. Filter Hygiene skips filters that don't need changes (e.g., already-private filters when using "Make Private").

Security & Privacy

• Runs entirely on Atlassian Forge.
• No customer data is sent to external services.
• Forge storage is used for preferences, Recent Activity, cleanup queue state, bounded hygiene snapshots, and operational counters.
• All actions use the logged-in user's permissions, ensuring proper access control.
• Deletion uses delete:filter:jira only for the explicit Delete Filters action.
• Eligible owner/share undo uses an exact compare-and-set guard: if Jira no longer matches the recorded post-action state, restoration stops rather than overwriting a newer change.

FAQ

Does it work with Jira Service Management?

Yes. Filter Hygiene supports Jira Software, Service Management, and Work Management (Cloud).

Will it delete filters?

Yes. Admins can delete exactly one reviewed filter after a repeated live impact preflight and typed DELETE confirmation. Deleted filters cannot be restored by Filter Hygiene.

Can I undo changes?

Eligible recent owner/share changes can be undone from Recent Activity while the undo window is open and Jira still exactly matches the recorded post-action state. Any intervening owner/share change blocks restoration. Jira can also reject restoration. Deletion has no Filter Hygiene undo.

What dependency coverage does Filter Hygiene support?

It checks direct Jira Software boards and incoming references from the accessible saved-filter corpus. Dashboard gadgets, JSM queues, standalone reports, automations, exports, subscriptions Jira does not return, and external consumers remain unavailable or unchecked.

Does zero supported impact mean safe to delete?

No. Zero returned direct boards or saved-filter references is not proof that a filter is unused or safe to delete. Review unsupported and inaccessible relationships manually.

Support

Need help or have a feature request? Contact us via the Marketplace listing support link. Include your site URL and a short description of the issue.

What to send support

• Jira site URL, for example https://example.atlassian.net/jira.
• Current browser URL where you got stuck.
• Screenshot of the page you are on.
• Whether you are in Jira, Jira admin settings, Atlassian Administration, Marketplace, or a native Jira filter page.
• The scan criteria used: filter name, owner, visibility, private-filter inclusion, or full scan.
• The action you attempted: scan, export CSV, reassign owner, make private, remove global share, or other.
• Your role on the site: Jira admin, project admin, org admin, evaluator, or other.

Related documentation

Product pages provide current positioning and Marketplace links; documentation pages provide operating details.

Governance and evidence docs

• AI Clearance (tools/models catalog)
• Access Evidence

Jira admin, handoff, and flow docs

• DriftGuard
• Filter Hygiene
• ImpactLoop
• Label Doctor
• TaskPort