Skip to content

Getting Started

Jump to bottom
Andy Haas edited this page Feb 18, 2026 · 1 revision

Getting Started

Requirements

  • Python 3.7+
  • requests – install with pip install -r requirements.txt
  • A Salesforce org and a Connected App (Consumer Key and Secret) for OAuth

1. Clone and install

git clone https://github.com/AndyHaas/Salesforce-Data-Usage-Analyzer.git
cd Salesforce-Data-Usage-Analyzer
python3 -m venv venv
source venv/bin/activate   # Windows: venv\Scripts\activate
pip install -r requirements.txt

2. Create a Connected App (Salesforce)

  1. In Salesforce: Setup → App Manager → New Connected App (or Create → Apps → Connected Apps).
  2. Enable OAuth Settings.
  3. Callback URL: http://localhost:8080/callback (or the host/port you will use; default is port 8080).
  4. Select OAuth scopes (e.g. Access and manage your data (api), Perform requests at any time (refresh_token)).
  5. Save and note the Consumer Key and Consumer Secret.

3. Config file

Copy the example config and edit it with your org and Connected App details:

cp configs/config_example.json configs/config_myorg.json

Edit configs/config_myorg.json:

  • instance – Your org URL, e.g. https://yourorg.my.salesforce.com or https://yourorg--sandbox.my.salesforce.com
  • client_id – Connected App Consumer Key
  • client_secret – Connected App Consumer Secret
  • callback_port – Must match the port in your Connected App callback URL (default 8080)

Leave mode as "quick" for a first run (Lead, Account, Contact, Case, Opportunity), or set objects to a list of API names. See Config Reference for all options.

4. Run the analyzer

Interactive (recommended first time):

python data_usage_analyzer.py --config configs/config_myorg.json
  • A browser window opens for Salesforce login and consent.
  • After OAuth, the script queries metadata and data, writes CSV and JSON to output/, then starts a local server and opens the dashboard at http://localhost:8000/static/.
  • Press Enter in the terminal to stop the server.

Headless (e.g. CI or scheduled run):

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

No browser prompt; uses the config as-is. The dashboard will not open automatically; you can serve static/ and output/ yourself if needed.

5. Output

After a run you will have:

  • output/field_usage_YYYYMMDD_HHMMSS.csv – usage data (and per-object CSVs in full mode)
  • output/field_usage_YYYYMMDD_HHMMSS.json – same data as JSON for the dashboard
  • output/manifest.json – list of runs (the dashboard Data menu reads this)

Open the dashboard (or re-open http://localhost:8000/static/ if you run again) to switch runs and filter by objects and Usage %.

Troubleshooting

  • Port 8080 in use: Set callback_port in config to another port and update the Connected App callback URL to match (e.g. http://localhost:8081/callback).
  • Port 8000 in use: The script will tell you; open the URL it prints in your browser.
  • “No config” or missing config: Run without --config and the script will prompt for settings and can save a new config file.
  • OAuth errors: Ensure callback URL matches exactly (including http vs https, port, and path /callback).

Home

Setup & config

Using the app

Clone this wiki locally