ArdSaor

Filter Hygiene for Jira — Documentation

Filter Hygiene helps Jira admins turn saved-filter sprawl into a reviewable cleanup workflow. Scan for risky sharing, owner drift, stale usage, invalid JQL, and duplicate queries; run read-only preflight before supported owner/share/deletion actions; and export evidence for managers, security teams, or auditors.

Current status

This documentation supports an active ArdSaor Marketplace app. Start from the product page for current positioning and Marketplace links, then use this guide for operating details.

Quick Start / After Install

Start in the Jira product, not Atlassian Administration. Open https://<site>.atlassian.net/jira. Filter Hygiene is configured inside Jira product administration; Marketplace listing/details and org-level administration are not the scan or cleanup surface.

Surface map

  • Admin/setup surface: scan filters, review risk, export CSV, reassign owners, make filters private, remove global shares, delete reviewed obsolete filters, and review recent activity. Reach it from Jira settings → Apps → Filter Hygiene.
  • Jira filter surface: individual filter links open the native Jira saved filter page so admins can inspect the filter in context.
  • Marketplace surface: install, billing, app details, and uninstall. It is not where scans or bulk actions run.

Five-minute path

  1. Open https://<site>.atlassian.net/jira.
  2. Open Jira settings → Apps → Filter Hygiene.
  3. Run a narrow scan first, such as visibility = Global or a known owner.
  4. Review risk, visibility, owner, JQL status, duplicate group, and recommended action before selecting anything for cleanup.
  5. Export CSV or a cleanup summary if you want a manager/audit snapshot before cleanup.
  6. Apply one small supported action first, such as removing global share from a disposable or low-risk filter after the read-only preflight passes. Test deletion only on disposable filters.
  7. Open Recent Activity to confirm the before/after record was written and whether undo is available.

If you are in Atlassian Administration

Atlassian Administration is the org-level surface under admin.atlassian.com. Use it for organization, users, billing, and connected apps. Filter Hygiene setup and cleanup lives in Jira product settings. Go to https://<site>.atlassian.net/jira, then open Jira settings → Apps → Filter Hygiene.

If Filter Hygiene is missing

  • Confirm you are in the correct Jira Cloud site.
  • Confirm Filter Hygiene is installed and licensed on that site.
  • Confirm your user has Jira admin rights for the product site; org admin alone may not be enough.
  • Refresh Jira after install. Forge app entries can take a short time to appear.

Use the Atlassian site link helper if you only have a site name and need Jira home or Manage apps links.

Setup screenshots

Jira product admin showing the Filter Hygiene app entry under Apps and explaining that Marketplace details are not the setup panel.
Find Filter Hygiene in Jira: open Jira settings, keep Marketplace apps selected, then click Filter Hygiene under Apps.
Filter Hygiene setup surface showing scan settings, filter visibility and owner controls, scan actions, and CSV export controls.
First setup surface: run a focused scan, review owner and visibility risk, then export CSV or apply targeted cleanup.
Atlassian Administration Apps page marked as the wrong surface for Filter Hygiene first setup.
Wrong surface: Atlassian Administration is for org administration; Filter Hygiene setup lives in Jira product settings.

Interface screenshots

Filter Hygiene screenshot showing permanent filter deletion preflight with dependency warnings and typed DELETE confirmation.
Deletion preflight: inspect irreversible deletion warnings, dependency caveats, and typed confirmation before deleting selected filters.

Contents

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, validate:jql:jira, write:filter:jira, delete:filter:jira, and storage:app
  • Data handled: filter metadata, owner/share data, JQL validation state, last-used signals, 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 filters matching your criteria, or "Full scan" to scan all filters.
  4. Review the risk dashboard, JQL status, duplicate groups, visibility, owner, and recommended action before adding filters to the cleanup queue or running a supported bulk action.

Understanding Results

  • Risk indicator: Filters are flagged by risk level based on share scope, owner state, stale-usage signals, JQL validation, duplicate normalized queries, and missing descriptions:
    • High risk: typically globally/logged-in shared filters or other high-impact cleanup candidates
    • Medium risk: often duplicates, group/project shares, or owner/staleness signals that deserve review
    • Low risk: filters with lower immediate cleanup urgency
  • Visibility: Shows the current share scope (Private, Project, Group, Global, or Mixed)
  • Owner: The user who owns the filter
  • JQL, duplicate, and stale signals: Shows whether Jira can validate the JQL, whether normalized query text matches other filters in the scan, and approximate last-used metadata where available
  • Filter link: Click the filter name to open it in Jira

Bulk Actions

Select multiple filters using the checkboxes, then choose an action from the Actions dropdown:

  • 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 selected filters after live preflight and typed DELETE confirmation. Deleted filters cannot be restored by Filter Hygiene.

All bulk actions show a read-only backend preflight with live Jira owner/share data, planned changes, blocked filters, warnings, and restore availability before execution. Deletion preflight includes irreversible deletion and dependency warnings; confirm dashboards, boards, gadgets, subscriptions, automations, and external reporting dependencies before deleting production filters.

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)
  • Delete filter: Permanently delete a reviewed filter after 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 summary, risk, risk reasons, JQL status, duplicate group, owner activity, recommended action, and last-used signal.

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, counts, risk buckets, and review notes.

Best Practices

  • Start by scanning for globally-shared filters to identify the highest-risk items first.
  • 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 bulk actions on a small selection and review the preflight blockers before applying to many filters.
  • Use deletion only after reviewing dashboard, board, gadget, subscription, automation, and external reporting dependencies.

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.

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 selected filters after a live 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 enough restore data is available. Undo can still fail if Jira rejects ownership or permission restoration. Deletion has no Filter Hygiene undo.

What happens to dashboards using modified filters?

Dashboards will continue to work if the dashboard owner still has access to the filter. If a filter is made private, dashboard users who aren't the filter owner may lose access to that gadget's data. If a filter is deleted, dashboards, boards, gadgets, subscriptions, automations, and external reports that depended on it may break.

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

Jira admin, handoff, and flow docs