FieldRat Help

Install, scan, and retire fields without developer guesswork.

Practical docs for Salesforce admins using FieldRat. Start with setup, then run Field Analysis, Quick Scan, or Deep Scan. FieldRat can generate the package.xml for selected metadata types, so admins do not have to hand-build retrieval files.

Install & First-Time Setup

Assign both FieldRat permission sets and verify Admin Setup.

Before You Start

  • Install and test in a sandbox first when possible.
  • Use a Salesforce admin or delegated admin user.
  • Assign both required permission sets to the user who configures and runs scans.

Required Permission Sets

  • FR FieldRat Admin
  • FR Cloud Engine Principal Access

Setup Steps

  • Install the FieldRat managed package.
  • Open the FieldRat app and go to Admin Setup.
  • Confirm the permission sets check passes.
  • Confirm secure authentication is active.
  • Click Check Connection to verify the Metadata Scan Engine.
  • Review monthly scan allowances and ZIP upload limit.

Run Your First Field Analysis

Find low-usage field candidates before dependency scanning.

Flow

  • Open New Run.
  • Choose a Salesforce object.
  • Set a population or usage threshold.
  • Choose the field scope.
  • Run Field Analysis and review the low-usage results.

What The Threshold Does

  • FieldRat analyzes every field on the selected object.
  • The threshold only flags low-usage candidates; it does not limit which fields are analyzed.

Field Dictionary Guide

Use the org-wide field inventory before cleanup decisions.

Use It For

  • Searching object and field metadata.
  • Exporting a point-in-time field catalog.
  • Finding ownership, type, and cleanup candidates before deeper scans.

Important

  • Field Dictionary is not a dependency scan by itself.
  • Quick Scan and Deep Scan show where fields are referenced.

Quick Scan Guide

Run a fast native Salesforce dependency check with no ZIP upload.

Why Use Quick Scan

  • Runs inside Salesforce.
  • No file upload required.
  • Best for fast checks across critical metadata types.

When It Is Enough

  • You need a quick dependency read before triage.
  • The fields are lower risk.
  • You want native in-org coverage without preparing metadata files.

Deep Scan & Metadata ZIP Guide

Generate package.xml, retrieve metadata, and upload a ZIP for broader coverage.

Why It Is Admin-Friendly

  • FieldRat generates package.xml for the metadata types you select.
  • You do not have to hand-build the manifest.
  • If you change metadata type selections, download package.xml again before retrieving metadata.

Deep Scan Flow

  • Choose Deep Scan.
  • Select metadata types.
  • Click Download package.xml.
  • Retrieve metadata in VS Code or Salesforce CLI.
  • Zip the force-app folder.
  • Upload the ZIP and launch the dependency scan.

What Happens To The ZIP

  • FieldRat scans metadata references, not business record values.
  • The uploaded file is automatically deleted after deep analysis completes.

Results, Risk Score & Cleanup Evidence

Read dependency results and export audit-ready cleanup evidence.

Review

  • Dependencies found by metadata type.
  • Deletion risk score and blast radius.
  • Run record details inside Salesforce.
  • Excel workbook evidence for cleanup review.

Decision Rule

  • Do not delete based on low usage alone.
  • Review dependencies, business ownership, and reporting impact before retirement.

Run Comparison

Compare two completed runs to spot field-usage drift and dependency changes.

Use It For

  • Comparing a baseline run against a newer run for the same object.
  • Finding degraded, recovered, cleared, and newly dependent fields.
  • Showing before-and-after cleanup progress in stakeholder reviews.

What To Review

  • Candidate delta and average population percentage delta.
  • Dependency count movement by Blocking, Structural, and Reporting categories.
  • Recent trend rows that show whether field health is improving or drifting.

Best Timing

  • After a cleanup sprint.
  • Before and after a release or data migration.
  • During monthly field-governance reviews.

Scheduler

Schedule recurring Field Analysis runs while keeping dependency scans manual.

What It Schedules

  • Field Usage Analysis only.
  • Selected objects, field scope, run cadence, and low-usage cutoff.
  • Optional alert email for scheduled-run failures.

What It Does Not Schedule

  • Quick Scan is not scheduled automatically.
  • Deep Scan is not scheduled automatically.
  • Admins stay in control of monthly cloud-scan quota usage.

Daily Operation

  • Create schedules from the Scheduler tab.
  • Pause, resume, remove, or refresh schedule status.
  • Review recent scheduled runs below the schedule list.

Security & Data Handling

Understand what stays in Salesforce and what is sent for Deep Scan.

Quick Scan

  • Runs natively inside Salesforce.
  • No metadata ZIP upload.
  • No business record values leave your org.

Deep Scan

  • Processes metadata files from the uploaded ZIP.
  • Does not process Salesforce business record values.
  • Uploaded ZIP is deleted after the scan completes.

Troubleshooting & FAQ

Fix common setup, retrieve, upload, and scan issues.

Common Checks

  • Confirm both FieldRat permission sets are assigned.
  • Run Check Connection from Admin Setup.
  • Download a fresh package.xml after changing selected metadata types.
  • Zip the force-app folder, not the entire temporary project folder.

When To Contact FieldRat

  • Include package version, scan mode, object API name, and the exact error message.
  • Do not send business record data unless FieldRat support explicitly asks for a safe sample.
Need help?

Send the exact error message plus package version, scan mode, object API name, and whether you used Quick Scan or Deep Scan.