Project Atlas AetherDev project hub
Atlas project production

BOUSD-MonthlyAttendance-Extract

Refresh attendance source tabs from Aeries into Google Sheets for the monthly attendance dashboard and related reporting views.

Internal-only entry. Do not publish externally without review.
Type
Field Tool
Lifecycle
Active
Last touched
2026-03-26
Visibility
Internal

Purpose

Keep attendance source tabs current so district and site leaders can use the monthly attendance dashboard without repeated manual SQL work.

Current state

Implementation evidence confirms automated tab refresh wiring: `run.sh` executes `conf.d/year-bygrade.toml` and `conf.d/year-byschool.toml`, then overwrites `SourceData-year-bygrade!A1:ZZ10000` and `SourceData-year-byschool!A1:ZZ10000`. `aether/docs/cron-example.txt` shows hourly weekday scheduling (`0 7-18 * * 1-5`) from `/home/bousdtech/repos/BOUSD-MonthlyAttendance-Extract/run.sh`, and host normalization maps this cron runtime primarily to `sal-01.bousd.us`. This automated extract path is the normal production refresh path. The dashboard README manual SQL/paste checklist is retained as legacy fallback/reference guidance.

Next step

Complete fallback ownership fields in the [MonthlyAttendance Fallback Runbook Scaffold](../monthlyattendance-fallback-runbook-scaffold/) and reconcile technical operator, business sign-off owner, fallback operator, and escalation owner in the [Owner, Escalation, and Fallback Matrix](../owner-escalation-and-fallback-matrix/).

Interfaces

Inputs
  • SQL query files
  • TOML configuration
  • ODBC connection settings
  • Google service-account access
Outputs
  • year-bygrade and year-byschool sheet tabs
  • local CSV artifacts
  • dashboard source data

Reality to Action trace

Reality Ingestion

Contributes in this stage.

Canonical Storage

Not in scope.

Automation Engines

Not in scope.

Human Interfaces

Contributes in this stage.

Operational Adoption

Contributes in this stage.

Core workflow

TBD. Document the 5-10 steps that define the core workflow.

Data integrity and contracts

Source of truth rules

  • Aeries is canonical for the extracted data.
  • Destination sheets are operational distribution surfaces and should not become the authoring system.

Safe handling

  • Restrict service-account keys and ODBC credentials to approved operators.
  • Treat CSV artifacts and destination tabs as restricted operational data.
  • Document host ownership and recovery steps in an internal runbook.

Operational notes

Reliability posture

The extract runtime is deterministic (`year-bygrade` + `year-byschool` configs to fixed sheet ranges) with cron-path evidence in `aether/docs/cron-example.txt`. Host normalization now places this workload on the primary Linux automation host (`sal-01.bousd.us`). `run.sh` contains no native notification/escalation logic, so support response still depends on external scheduler/operations monitoring.

Observability

  • stdout/stderr from run.sh and bundled CLI tools
  • CSV artifacts in data/ and temp/ (`year-bygrade.csv`, `year-byschool.csv`)
  • stale or missing downstream sheet tabs

Security and privacy

These jobs move restricted operational data from Aeries into Google Sheets. Keep service-account keys, credentials, logs, and CSV artifacts private.

Dependencies

Upstream
  • Aeries SQL access
  • ODBC driver stability
  • service-account sharing
  • scheduler ownership
Downstream
  • BOUSD-MonthlyAttendance-Dashboard
  • attendance visibility workflows

Ownership

Owners

Technology Services, Josh Barton

Users

Technology Services, district reporting stakeholders

BOUSD-MonthlyAttendance-Extract

Operational Notes

  • Implementation pattern: run.sh wrapper, conf.d/ configuration, SQL-over-ODBC extraction, local CSV artifacts, and controlled Google Sheets range overwrites.
  • Extract contracts in code: year-bygrade and year-byschool each map to SourceData-<name>!A1:ZZ10000 with full-range overwrite.
  • Scheduled cadence: Hourly on weekdays between 07:00 and 18:00; repo evidence uses 0 7-18 * * 1-5 /home/bousdtech/repos/BOUSD-MonthlyAttendance-Extract/run.sh.
  • Runtime host context: Linux cron execution is now normalized to sal-01.bousd.us for this extract family.
  • Manual SQL/paste steps in dashboard repo documentation are now treated as legacy fallback/reference guidance, not routine refresh.
  • Alerting note: extract script handles data movement only; no in-repo mailer or notifier path is documented in this repo.
  • Governance note: owner/escalation/fallback fields for this workflow are tracked in the Owner, Escalation, and Fallback Matrix.
  • Shared family risks include sheet header drift, secret sprawl, owner/escalation coverage gaps, and weak centralized monitoring.

Registry Alignment

  • Mapped registry entry: INT-003.
  • Registry context: this feed also belongs to the Aeries-to-Google Sheets reporting extract family, which Atlas keeps as operational family context rather than as a standalone BOUSD integration.
  • Registry clarified: this is the production upstream feed for the attendance dashboard, not just a repo-level helper script.
  • Validation gaps: destination tab contracts, scheduler path, and primary host context (sal-01) are now evidence-backed; remaining fallback/operator/escalation fields are tracked in the MonthlyAttendance Fallback Runbook Scaffold and Owner, Escalation, and Fallback Matrix.