Actualsboard · VG Guide

The actualsboard pulls live expense data from QuickBooks Online and generates an HTML report showing actuals and budget variance across all active VG properties. No CSV exports, no spreadsheet edits — one command produces a fresh report.

§ 01

How to Run the Report

Open Terminal and navigate to the vg/ directory

cd "/Users/mac/My Drive (randall@opsstrategypro.com)/RWP/02_active/vg"

Run the build script

python3 workspaces/actualsboard/scripts/build_report.py

Open the output file

published/reports/actualsboard/actualsboard-YYYY-MM-DD.html

§ 02

What the Report Shows

Section	What it Contains	Which Properties
Active Construction panel	Actuals + approved budget + variance per WO code. Red OVER badge when actual exceeds budget.	status: active-construction only
All Properties panel	Total actuals + WO category breakdown in a compact table.	All include: true properties
Overruns queue	WO codes where actual spend exceeds the approved budget.	Active construction only
Budget Gaps queue	WO codes with real spend but no budget amount set in budgets.yaml.	Active construction only
Unmapped Items queue	QB line items whose Product/Service name is not in cost_code_mapping.yaml. These are not counted in any WO total until mapped.	All properties

§ 03

Re-Authorizing QuickBooks (First Time or After Token Expiry)

Delete the existing token file (if present)

rm ~/.config/vg/qb_token.json

Run the auth script — it will print a URL

python3 workspaces/actualsboard/scripts/qb_auth.py

Open the printed URL in your browser and click Connect in QuickBooks

Browser redirects to opsstrategypro.com/qb-callback — page may not load, that is fine

Copy the full redirect URL from the browser address bar and paste it back into the terminal prompt

Starts with: https://opsstrategypro.com/qb-callback?code=...

Terminal prints: Token saved. Run build_report.py normally.

Token stored at ~/.config/vg/qb_token.json — auto-refreshes on subsequent runs

§ 04

Config Files — What to Edit and When

File	Edit When	Key Fields
config/properties.yaml	Adding a new property or changing a property's status	short_name, qb_custom_field_value (must match QB CustomerRef), status, include
config/budgets.yaml	Approving a new WO budget or updating an existing budget amount	Keyed by property short_name → WO code → dollar amount
config/cost_code_mapping.yaml	A QB Product/Service item appears in the Unmapped Items queue	QB item name (exact string) → VG WO code

§ 05

Clearing the Unmapped Items Queue

Steps

Open the report and scroll to the Unmapped Items exception table at the bottom

Each row is a QB line item whose Product/Service name has no mapping

For each item name, find the matching VG WO code using reference/cost-codes/Cost Code Unified.csv

The CSV has every QB item name and its parent WO code in column A and B

Add a line to config/cost_code_mapping.yaml: "QB Item Name": WO_CODE

Exact string match required — copy the item name directly from the report

Re-run build_report.py and verify the item no longer appears in the queue

§ 06

File Locations

workspaces/actualsboard/

├── config/

│ ├── properties.yaml ← property list + QB match values

│ ├── budgets.yaml ← approved WO budgets per property

│ └── cost_code_mapping.yaml ← QB item name → VG WO code

├── scripts/

│ ├── qb_auth.py ← OAuth token (run once to authorize)

│ ├── qb_client.py ← fetches Bills + Purchases from QB

│ ├── cost_code_mapper.py ← maps item names to WO codes

│ └── build_report.py ← main entry point

└── templates/

└── report.html.j2 ← report layout and styling

published/reports/actualsboard/

└── actualsboard-YYYY-MM-DD.html ← output (one file per run date)

§ 07

QB Credentials

Client ID and Client Secret are stored in RWP/.env as QUICKBOOKS_CLIENT_ID and QUICKBOOKS_CLIENT_SECRET. These are the Production keys from the Intuit Developer portal (developer.intuit.com → your app → Keys & OAuth → Production tab).

The OAuth token (access + refresh) is stored at ~/.config/vg/qb_token.json and auto-refreshes on each report run. If the refresh fails (e.g. after a long gap), delete the token file and re-authorize using the steps above.

Actualsboard How to run, read, and maintain the QB expense dashboard