Instance Cleanup Documentation
Complete guide to auditing your Jira Cloud instance, understanding health scores, and safely cleaning up unused configurations.
Overview
Instance Cleanup Auditor is a Jira Cloud app that helps administrators identify and remove unused configurations that accumulate over time. It provides automated auditing across workflows, schemes, custom fields, users, and projects.
Key Features
- Health Score Dashboard — Instant 0-100 score with category breakdowns
- Comprehensive Auditors — Workflows, schemes, fields, users, projects, and more
- Safe Cleanup Actions — Dry-run mode, confirmation dialogs, and audit logging
- PDF Reports — Downloadable reports for stakeholders
- Runs on Atlassian — Built on Forge, 100% hosted on Atlassian infrastructure
🚧 Coming Soon: Instance Cleanup Auditor is currently in development and will be available on the Atlassian Marketplace soon.
Installation
Instance Cleanup can be installed from the Atlassian Marketplace by a Jira administrator.
Requirements
- Jira Cloud (Software, Service Management, or Work Management)
- Jira administrator permissions to install apps
- Jira administrator permissions to run audits and cleanup actions
Installation Steps
- Go to Jira Settings → Apps → Find new apps
- Search for "Instance Cleanup"
- Click Get app and follow the prompts
- Once installed, access the app via Apps → Instance Cleanup
Quick Start
Get started with Instance Cleanup in 5 minutes:
- Install the app from the Atlassian Marketplace
- Open the dashboard — Navigate to Apps → Instance Cleanup
- Run an audit — Click "Run Full Audit" to scan your instance
- Review results — See your health score and issues found
- Clean up — Use the cleanup actions to remove unused items
✓ Tip: Start with the Workflow Auditor — inactive workflows are often the biggest source of instance cruft.
Health Dashboard
The Health Dashboard provides an at-a-glance view of your Jira instance health with an overall score and category breakdowns.
Dashboard Components
- Overall Health Score — A 0-100 score representing your instance's overall health
- Category Scores — Individual scores for workflows, schemes, fields, users, and projects
- Issues Found — Count of issues discovered in each category
- Trend Chart — Track how your health score changes over time
- Top Recommendations — Prioritized list of cleanup actions
Score Calculation
The overall health score is calculated as a weighted average of category scores.
Category Weights
| Category | Weight | Rationale |
|---|---|---|
| Workflows | 25% | High impact on performance and user experience |
| Custom Fields | 25% | Direct impact on reindexing and search performance |
| Schemes | 20% | Admin complexity and configuration overhead |
| Users | 20% | License costs and security implications |
| Projects | 10% | Lower direct impact but contributes to clutter |
Category Score Factors
Each category starts at 100 points and deductions are made for issues found:
| Issue Type | Deduction |
|---|---|
| Inactive workflow | -5 points |
| Orphaned workflow scheme | -3 points |
| Complex workflow (>20 statuses) | -10 points |
| Unused custom field | -5 points |
| Duplicate-named field | -3 points |
| User inactive >90 days | -1 point |
| User inactive >180 days | -2 points |
| Empty project | -10 points |
Interpreting Scores
Use this guide to understand what your health score means:
| Score | Rating | Recommended Action |
|---|---|---|
| 90-100 | Excellent | Maintain current practices. Run quarterly checks. |
| 70-89 | Good | Minor cleanup recommended. Address high-priority items. |
| 50-69 | Fair | Cleanup needed. Schedule dedicated cleanup time. |
| 30-49 | Poor | Significant cleanup required. Consider phased approach. |
| 0-29 | Critical | Urgent cleanup needed. May be affecting performance. |
Workflow Auditor
The Workflow Auditor scans all workflows and workflow schemes in your instance.
What It Checks
- Inactive Workflows — Workflows not assigned to any workflow scheme
- Orphaned Workflow Schemes — Schemes not assigned to any project
- Duplicate Workflows — Workflows with identical or near-identical status sets
- Complex Workflows — Workflows with excessive statuses (>15) or transitions
- Unused Statuses — Statuses not used in any active workflow
Interpreting Results
Workflow issues are categorized by severity:
- High — Inactive workflows and orphaned schemes (safe to delete)
- Medium — Complex workflows (consider simplifying)
- Low — Duplicate workflows (consider consolidating)
Scheme Auditor
The Scheme Auditor scans all scheme types in your instance.
Scheme Types Audited
- Screen Schemes — Schemes not used by any issue type screen scheme
- Screens — Screens not used in any screen scheme or workflow
- Field Configurations — Configs not used in any scheme
- Permission Schemes — Schemes not assigned to any project
- Notification Schemes — Schemes not assigned to any project
- Issue Type Schemes — Schemes not assigned to any project
Field Auditor
The Field Auditor analyzes all custom fields in your instance.
What It Checks
- Unused Fields — Fields not configured on any screen or context
- Duplicate Fields — Fields with identical or very similar names
- Empty Fields — Fields with no values across all issues
- Low Usage Fields — Fields used by less than 1% of issues
- Trashed Fields — Fields in trash approaching permanent deletion
Caution: Before deleting custom fields, ensure they're not used in automation rules, filters, or external integrations.
User Auditor
The User Auditor identifies inactive users and potential license savings.
What It Checks
- Inactive Users — Users who haven't logged in for X days (configurable: 30/60/90/180)
- Never Logged In — Users who were added but never accessed Jira
- License Impact — Estimated monthly savings from deactivating inactive users
Inactivity Thresholds
| Threshold | Recommendation |
|---|---|
| 30 days | Monitor — may be on leave or low-frequency user |
| 60 days | Review — reach out to confirm still needs access |
| 90 days | Consider — likely candidate for deactivation |
| 180 days | Deactivate — very likely no longer needs access |
Project Auditor
The Project Auditor identifies empty and stale projects.
What It Checks
- Empty Projects — Projects with zero issues
- Stale Projects — Projects with no issue activity for X months
- Archive Candidates — Projects recommended for archiving based on activity
Safe Cleanup
Instance Cleanup provides safe cleanup actions with multiple safeguards.
Cleanup Safeguards
- Confirmation Dialogs — Every delete action requires explicit confirmation
- Impact Warnings — Clear explanation of what will be affected
- Dry Run Mode — Preview changes before executing
- Audit Logging — All actions are logged with timestamp and user
- Bulk Selection — Select multiple items but review before deletion
Dry Run Mode
Dry Run Mode lets you preview cleanup actions without making any changes.
How It Works
- Select items you want to clean up
- Click "Preview Changes" (Dry Run)
- Review the list of items that would be deleted
- If satisfied, click "Execute Cleanup"
- Or cancel to make adjustments
Tip: Always use Dry Run Mode when cleaning up for the first time to understand the impact.
Audit Logging
All cleanup actions are logged for accountability and compliance.
Log Contents
- Timestamp — When the action was performed
- User — Who performed the action
- Action Type — Delete, archive, or modify
- Items Affected — List of items that were changed
- Result — Success or failure with any error messages
Permissions
Instance Cleanup requires the following Jira permissions:
| Permission | Purpose |
|---|---|
read:jira-work |
Read issue data for usage statistics |
read:jira-user |
Read user information for activity analysis |
manage:jira-configuration |
Read and manage workflows, schemes, and fields |
manage:jira-project |
Read project data and manage project settings |
storage:app |
Store health snapshots, audit logs, and preferences |
Privacy: Instance Cleanup runs entirely on Atlassian infrastructure. Your data never leaves Atlassian's servers.
Troubleshooting
Audit takes too long
For large instances (>500 users, >1000 projects), audits may take several minutes. The app processes data in batches to avoid timeouts. You can:
- Run individual auditors instead of a full audit
- Schedule audits during off-peak hours
Can't delete an item
Some items may have hidden dependencies. Check:
- Automation rules referencing the item
- JQL filters using the field
- Boards or dashboards with dependencies
Health score seems wrong
The score is based on automated analysis which may not account for intentional configurations. You can:
- Mark items as "intentional" to exclude from scoring
- Adjust thresholds in settings
Frequently Asked Questions
Will cleanup actions affect my production issues?
No. Instance Cleanup only removes configuration items (workflows, schemes, fields) that are not in use. It never deletes or modifies actual issues.
Can I undo a cleanup action?
Some items can be restored from Jira's trash (custom fields, projects). Workflows and schemes cannot be restored once deleted, which is why we recommend using Dry Run Mode first.
How often should I run an audit?
We recommend running a full audit quarterly. You can run more frequent audits on specific categories (e.g., monthly user audits before license renewals).
Does this work with Jira Service Management?
Yes. Instance Cleanup works with Jira Cloud regardless of whether you're using Jira Software, Jira Service Management, or Jira Work Management.
Is my data secure?
Yes. Instance Cleanup is built on Atlassian Forge and runs 100% on Atlassian's infrastructure. Your data never leaves Atlassian's servers, and the app qualifies for the "Runs on Atlassian" trust badge.