Skip to content

README.md

Latest commit

 

History

History
62 lines (46 loc) · 4.71 KB

README.md

File metadata and controls

62 lines (46 loc) · 4.71 KB

Salesforce Data Usage Analyzer

This tool uses the Salesforce API to process Custom and Standard Objects and every individual field, then outputs a CSV and an interactive HTML dashboard of field usage (filled vs empty counts, usage %, and charts).

Documentation: For setup, config reference, and dashboard guide, see the Wiki. The wiki is the GitHub wiki repo, linked as the .wiki submodule; after cloning the main repo, run git submodule update --init to populate .wiki for local wiki editing.

Requirements

  • Python 3.7+
  • requests (see requirements.txt)
  • Salesforce CLI (sf on your PATH)
  • An authorized org in that CLI (for example sf org login web, then sf config set target-org <alias>)

Quick start

  1. Authorize the org (same idea as other Milestone Salesforce tooling, e.g. Salesforce-Permissions-Analysis): use sf to log in and optionally set a default org. The analyzer reads the session with sf org display --json (no Connected App or OAuth callback in this repo).

  2. Config: Copy the example and set analysis options.

    cp configs/config_example.json configs/config_myorg.json

    Edit configs/config_myorg.json: optional instance (for your notes or to warn if it does not match the CLI org), optional target_org (org alias or username passed as sf org display --target-org; omit or null to use the CLI default org), optional api_version (otherwise the org’s API version is used), mode, objects, exclusion_objects, etc. See the Wiki – Config reference for all options. Use exclusion_objects to skip objects that are not queryable or not needed (e.g. ApexClass, SetupAuditTrail, TabDefinition); the tool excludes many system/event objects by default and, after a run, writes any failed objects to temp/failed_objects.json so you can add them to exclusion_objects for the next run.

  3. Install: pip install -r requirements.txt (recommend a virtual environment).

  4. Run:

    python data_usage_analyzer.py --config configs/config_myorg.json

    Interactive runs (no --silent): Step 1 picks a JSON config (retry on bad input; Other asks for a path — empty paths are rejected; type back there to return to the list). A short summary is shown, then Step 2 lists numbered Salesforce CLI orgs from sf org list --all (invalid choices re-prompt). The two steps use different number ranges on purpose.
    Headless: python data_usage_analyzer.py --silent --config configs/config_myorg.json
    Override org without editing the file: python data_usage_analyzer.py --config configs/config_myorg.json -o MySandboxAlias

  5. Output: The script writes to output/ and then opens the dashboard in your browser.

    • CSV: output/field_usage_YYYYMMDD_HHMMSS.csv (and per-object CSVs in full runs).
    • JSON: output/field_usage_YYYYMMDD_HHMMSS.json — combined field-usage data keyed by object.
    • Manifest: output/manifest.json — lists the latest run and all available runs for the dashboard Data menu.
    • Dashboard: Served at http://localhost:8000/static/ (port 8000). You can switch between runs via the header Data menu and filter by Objects and Usage %.

Dashboard

The dashboard (SLDS-styled single-page app in static/) includes:

  • Header: Data run selector, Objects filter (multi-select on main view; object switcher on object detail), back button, Help (wiki link).
  • Main view: Sortable object table (record counts, field counts, most/least used %), exclude list, charts (record counts by object, least utilized fields), toolbar (Usage % min/max, “View all low-usage fields”, “Export exclusion list”).
  • Object view: Per-object field table with Usage % and field-type filters, highlight panel (total/custom/standard/managed), “Fields to delete” list for export.
  • Low-usage view: All fields below the Usage % max threshold in one table.

Details and screenshots: Wiki – Dashboard.

Project layout

├── configs/
│   └── config_example.json   # Example config (copy and edit)
├── data_usage_analyzer.py    # Main script (CLI session, REST API, CSV/JSON, dashboard server)
├── requirements.txt
├── static/                   # Dashboard UI (HTML, JS, CSS, Chart.js, SLDS)
├── output/                   # Created at run: CSV, JSON, manifest.json
├── .wiki/                    # Optional: clone of GitHub wiki repo for editing
└── README.md