+
{% if settings.control_center_auto_refresh_next_run %}
- {{ settings.control_center_auto_refresh_next_run }}
+ Loading local time...
{% else %}
Will be calculated when saved
{% endif %}
@@ -12543,6 +12558,7 @@
controlCenterAutoRefreshToggle.addEventListener('change', toggleControlCenterAutoRefreshInputs);
toggleControlCenterAutoRefreshInputs();
}
+ displayControlCenterAutoRefreshLocalTime();
});
function toggleControlCenterAutoRefreshInputs() {
@@ -12554,6 +12570,35 @@
}
}
+ function displayControlCenterAutoRefreshLocalTime() {
+ const viewerTimezoneElement = document.getElementById('control-center-auto-refresh-viewer-timezone');
+ const nextRunElement = document.getElementById('control-center-auto-refresh-next-run');
+ const resolvedViewerTimezone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+ const viewerTimezone = resolvedViewerTimezone || 'local time';
+
+ if (viewerTimezoneElement) {
+ viewerTimezoneElement.textContent = viewerTimezone;
+ }
+ if (!nextRunElement || !nextRunElement.dataset.nextRunUtc) {
+ return;
+ }
+
+ const nextRun = new Date(nextRunElement.dataset.nextRunUtc);
+ if (Number.isNaN(nextRun.getTime())) {
+ nextRunElement.textContent = 'Unavailable';
+ return;
+ }
+
+ const formatOptions = {
+ dateStyle: 'medium',
+ timeStyle: 'short',
+ };
+ if (resolvedViewerTimezone) {
+ formatOptions.timeZone = resolvedViewerTimezone;
+ }
+ nextRunElement.textContent = `${nextRun.toLocaleString([], formatOptions)} (${viewerTimezone})`;
+ }
+
// Retention Policy Functions
// Toggle retention default sections visibility based on enable checkboxes
diff --git a/docs/explanation/features/CONTROL_CENTER_AUTO_REFRESH_SCHEDULE.md b/docs/explanation/features/CONTROL_CENTER_AUTO_REFRESH_SCHEDULE.md
index f898586b0..2e4a121bc 100644
--- a/docs/explanation/features/CONTROL_CENTER_AUTO_REFRESH_SCHEDULE.md
+++ b/docs/explanation/features/CONTROL_CENTER_AUTO_REFRESH_SCHEDULE.md
@@ -1,35 +1,47 @@
# Control Center Auto-Refresh Schedule
Implemented in version: **0.241.026**
+Updated in version: **0.250.102**
## Overview
-Control Center administrators can now configure a daily UTC refresh schedule for Control Center metrics. The setting is enabled by default and runs at **06:00 UTC** unless an administrator changes the time under Admin Settings > Control Center.
+Control Center administrators can configure a daily refresh schedule for cached Control Center metrics. The setting is enabled by default and new installations run at **02:00 America/New_York** unless an administrator changes the time under Admin Settings > Control Center. The IANA timezone keeps the recurring rule at 2:00 AM across Eastern Standard Time and Eastern Daylight Time.
## Technical Specifications
-- **Settings defaults**: `control_center_auto_refresh_enabled`, `control_center_auto_refresh_time`, `control_center_auto_refresh_hour`, `control_center_auto_refresh_minute`, and `control_center_auto_refresh_next_run` are defined in `application/single_app/functions_settings.py`.
-- **Schedule helpers**: `application/single_app/functions_control_center.py` normalizes the configured time and calculates the next daily UTC run.
+- **Dependency**: `tzdata==2026.3` supplies the IANA timezone database on platforms such as Windows that do not ship one with Python.
+- **Settings defaults**: `control_center_auto_refresh_enabled`, `control_center_auto_refresh_time`, `control_center_auto_refresh_hour`, `control_center_auto_refresh_minute`, `control_center_auto_refresh_timezone`, and `control_center_auto_refresh_next_run` are defined in `application/single_app/functions_settings.py`.
+- **Schedule helpers**: `application/single_app/functions_control_center.py` normalizes the configured wall-clock time and IANA timezone, then calculates the next run as a timezone-aware UTC timestamp.
- **Background execution**: `application/single_app/background_tasks.py` checks the schedule every five minutes and uses the existing distributed lock pattern before calling the Control Center refresh.
-- **Admin UI**: `application/single_app/templates/admin_settings.html` exposes the enable toggle, UTC time input, and next-run display under the Control Center settings tab.
-- **Status API**: `application/single_app/route_backend_control_center.py` returns auto-refresh schedule metadata from `/api/admin/control-center/refresh-status`.
-- **Version update**: `application/single_app/config.py` was updated to version **0.241.026** for this feature.
+- **Admin UI**: `application/single_app/templates/admin_settings.html` exposes the enable toggle, recurring time, configured timezone, browser timezone, and browser-local next-run display under the Control Center settings tab.
+- **Status API**: `application/single_app/route_backend_control_center.py` returns the recurring rule and canonical UTC next-run timestamp from `/api/admin/control-center/refresh-status`.
+- **Control Center display**: `application/single_app/static/js/control-center.js` formats last-run and next-run UTC timestamps in the viewer's browser timezone.
+- **Version update**: `application/single_app/config.py` was updated to version **0.250.102** for the DST-aware schedule and browser-local display.
+
+## Storage and Compatibility
+
+- Concrete timestamps such as `control_center_last_refresh` and `control_center_auto_refresh_next_run` are stored as timezone-aware UTC ISO values.
+- The recurring rule stores a wall-clock time plus an IANA timezone because a fixed UTC clock value cannot preserve a local run time across daylight-saving transitions.
+- Existing installations using the original 06:00 UTC default migrate to 02:00 `America/New_York`.
+- Existing custom UTC schedules retain their UTC behavior until an administrator changes the schedule.
## Usage Instructions
1. Open Admin Settings.
2. Select the Control Center tab.
3. Use Automatic Data Refresh to enable or disable the daily refresh.
-4. Set the refresh time in UTC. The default is 06:00.
-5. Save settings to calculate the next scheduled run.
+4. Set the refresh time. The default rule is 02:00 `America/New_York`.
+5. Review the browser-local next-run value and save settings.
## Testing and Validation
- Functional coverage: `functional_tests/test_control_center_auto_refresh_schedule.py`
- UI coverage: `ui_tests/test_admin_settings_control_center_auto_refresh.py`
-- The background scheduler preserves the existing manual refresh behavior and only runs the automatic refresh when the saved next-run timestamp is due.
+- The background scheduler preserves the existing manual refresh behavior and only runs the automatic refresh when the saved UTC next-run timestamp is due.
+- Regression coverage verifies winter, summer, spring-forward, and fall-back UTC calculations.
## Known Limitations
- The scheduler checks every five minutes, so the refresh may start a few minutes after the configured time.
-- The configured time is UTC-only to avoid ambiguity across app instances and regional deployments.
\ No newline at end of file
+- A configured time that does not exist during a spring-forward transition runs at the first valid instant after the skipped local hour.
+- Deployed environments must enable SimpleChat background tasks through `SIMPLECHAT_RUN_BACKGROUND_TASKS=1`.
\ No newline at end of file
diff --git a/docs/explanation/release_notes.md b/docs/explanation/release_notes.md
index 5a39ae650..165a7e0b0 100644
--- a/docs/explanation/release_notes.md
+++ b/docs/explanation/release_notes.md
@@ -6,6 +6,11 @@ For feature-focused and fix-focused drill-downs by version, see [Features by Ver
#### New Features
+* **Automatic Overnight Control Center Statistics Refresh**
+ * Added an enabled-by-default daily Control Center metrics refresh at 2:00 AM Eastern, with an administrator toggle and configurable time under Admin Settings > Control Center.
+ * The recurring schedule follows Eastern daylight-saving changes, stores concrete execution timestamps in UTC, and shows last-run and next-run values in each administrator's browser timezone.
+ * (Ref: Closes #706, `functions_control_center.py`, `background_tasks.py`, `admin_settings.html`, `control-center.js`)
+
* **Configurable Chat AI Notice**
* Administrators can display custom plain-text AI guidance directly below the chat composer.
* Supports non-dismissible, per-session, daily, and once-per-message-version behavior with validated dismissal persistence and automatic redisplay when the configured notice changes.
diff --git a/functional_tests/test_control_center_auto_refresh_schedule.py b/functional_tests/test_control_center_auto_refresh_schedule.py
index 992cf698c..bbe47b5d3 100644
--- a/functional_tests/test_control_center_auto_refresh_schedule.py
+++ b/functional_tests/test_control_center_auto_refresh_schedule.py
@@ -2,15 +2,19 @@
#!/usr/bin/env python3
"""
Functional test for Control Center auto-refresh scheduling.
-Version: 0.241.026
+Version: 0.250.102
Implemented in: 0.241.026
+Updated in: 0.250.102
-This test ensures administrators can configure the daily Control Center
-refresh schedule and that the background scheduler honors the saved UTC time.
+This test validates the enabled 02:00 Eastern default, timezone normalization,
+DST-aware UTC next-run timestamps, and scheduler/admin/status integration.
"""
+import importlib.util
import re
import sys
+import types
+from datetime import datetime, timezone
from pathlib import Path
@@ -22,125 +26,219 @@
ADMIN_SETTINGS_ROUTE_FILE = APP_DIR / "route_frontend_admin_settings.py"
CONTROL_CENTER_ROUTE_FILE = APP_DIR / "route_backend_control_center.py"
ADMIN_TEMPLATE_FILE = APP_DIR / "templates" / "admin_settings.html"
+CONTROL_CENTER_JS_FILE = APP_DIR / "static" / "js" / "control-center.js"
CONFIG_FILE = APP_DIR / "config.py"
+def load_control_center_module():
+ """Load schedule helpers without initializing external application clients."""
+ stub_modules = {
+ "config": types.SimpleNamespace(
+ cosmos_user_settings_container=None,
+ cosmos_groups_container=None,
+ ),
+ "functions_debug": types.SimpleNamespace(debug_print=lambda *args, **kwargs: None),
+ "functions_settings": types.SimpleNamespace(
+ get_settings=lambda: {},
+ update_settings=lambda settings: True,
+ ),
+ "functions_appinsights": types.SimpleNamespace(
+ log_event=lambda *args, **kwargs: None,
+ ),
+ }
+ original_modules = {}
+ for module_name, module in stub_modules.items():
+ original_modules[module_name] = sys.modules.get(module_name)
+ sys.modules[module_name] = module
+
+ try:
+ spec = importlib.util.spec_from_file_location(
+ "control_center_schedule_under_test",
+ CONTROL_CENTER_FUNCTIONS_FILE,
+ )
+ module = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(module)
+ return module
+ finally:
+ for module_name, original_module in original_modules.items():
+ if original_module is None:
+ sys.modules.pop(module_name, None)
+ else:
+ sys.modules[module_name] = original_module
+
+
def assert_contains(source, expected, description):
"""Assert that source contains expected text."""
if expected not in source:
raise AssertionError(f"Missing {description}: {expected}")
-def get_version():
- """Read the current application version from config.py."""
- config_source = CONFIG_FILE.read_text(encoding="utf-8")
- match = re.search(r'VERSION = "([^"]+)"', config_source)
- if not match:
- raise AssertionError("Could not find VERSION in config.py")
- return match.group(1)
-
-
-def test_default_settings(settings_source):
- """Validate default Control Center auto-refresh settings."""
- assert_contains(settings_source, "'control_center_auto_refresh_enabled': True", "enabled default")
- assert_contains(settings_source, "'control_center_auto_refresh_time': '06:00'", "06:00 UTC default")
- assert_contains(settings_source, "'control_center_auto_refresh_hour': 6", "hour default")
- assert_contains(settings_source, "'control_center_auto_refresh_minute': 0", "minute default")
- assert_contains(settings_source, "'control_center_auto_refresh_next_run': None", "next-run default")
-
-
-def test_schedule_helpers(control_center_source):
- """Validate schedule normalization and next-run helpers exist."""
- expected_snippets = [
- "CONTROL_CENTER_DEFAULT_AUTO_REFRESH_TIME = '06:00'",
- "def normalize_control_center_auto_refresh_time",
- "def calculate_next_control_center_auto_refresh_run",
- "def parse_control_center_auto_refresh_datetime",
- "next_run += timedelta(days=1)",
- "settings['control_center_auto_refresh_next_run'] = next_run.isoformat()",
- ]
- for snippet in expected_snippets:
- assert_contains(control_center_source, snippet, "Control Center schedule helper")
-
-
-def test_admin_settings_form(route_source, template_source):
- """Validate admin settings saves and renders the schedule controls."""
- route_snippets = [
- "control_center_auto_refresh_enabled = form_data.get('control_center_auto_refresh_enabled') == 'on'",
- "incoming_control_center_auto_refresh_time = form_data.get(",
- "control_center_auto_refresh_schedule_changed = (",
- "calculate_next_control_center_auto_refresh_run(",
- "'control_center_auto_refresh_time': control_center_auto_refresh_schedule['time']",
- ]
- for snippet in route_snippets:
- assert_contains(route_source, snippet, "admin route schedule persistence")
-
- template_snippets = [
- "id=\"control-center-auto-refresh-section\"",
- "id=\"control_center_auto_refresh_enabled\"",
- "id=\"control_center_auto_refresh_time\"",
- "value=\"{{ settings.control_center_auto_refresh_time or '06:00' }}\"",
- "toggleControlCenterAutoRefreshInputs",
- "classList.toggle('d-none'",
+def test_default_schedule(schedule_module):
+ """Validate the enabled 02:00 America/New_York default."""
+ schedule = schedule_module.get_control_center_auto_refresh_schedule({})
+ assert schedule == {
+ "hour": 2,
+ "minute": 0,
+ "time": "02:00",
+ "timezone": "America/New_York",
+ }
+
+ invalid_timezone_schedule = schedule_module.normalize_control_center_auto_refresh_time(
+ "04:15",
+ schedule_timezone="Not/A_Timezone",
+ )
+ assert invalid_timezone_schedule["time"] == "04:15"
+ assert invalid_timezone_schedule["timezone"] == "America/New_York"
+
+
+def test_dst_aware_utc_next_runs(schedule_module):
+ """Validate 02:00 Eastern resolves to the correct UTC time in winter and summer."""
+ settings = {
+ "control_center_auto_refresh_time": "02:00",
+ "control_center_auto_refresh_timezone": "America/New_York",
+ }
+
+ winter_now = datetime(2026, 1, 15, 6, 30, tzinfo=timezone.utc)
+ winter_next_run = schedule_module.calculate_next_control_center_auto_refresh_run(
+ settings,
+ current_time=winter_now,
+ )
+ assert winter_next_run == datetime(2026, 1, 15, 7, 0, tzinfo=timezone.utc)
+
+ summer_now = datetime(2026, 7, 15, 5, 30, tzinfo=timezone.utc)
+ summer_next_run = schedule_module.calculate_next_control_center_auto_refresh_run(
+ settings,
+ current_time=summer_now,
+ )
+ assert summer_next_run == datetime(2026, 7, 15, 6, 0, tzinfo=timezone.utc)
+
+
+def test_dst_transition_days(schedule_module):
+ """Validate deterministic UTC timestamps on Eastern DST transition days."""
+ settings = {
+ "control_center_auto_refresh_time": "02:00",
+ "control_center_auto_refresh_timezone": "America/New_York",
+ }
+
+ spring_now = datetime(2026, 3, 8, 6, 30, tzinfo=timezone.utc)
+ spring_next_run = schedule_module.calculate_next_control_center_auto_refresh_run(
+ settings,
+ current_time=spring_now,
+ )
+ assert spring_next_run == datetime(2026, 3, 8, 7, 0, tzinfo=timezone.utc)
+
+ fall_now = datetime(2026, 11, 1, 6, 30, tzinfo=timezone.utc)
+ fall_next_run = schedule_module.calculate_next_control_center_auto_refresh_run(
+ settings,
+ current_time=fall_now,
+ )
+ assert fall_next_run == datetime(2026, 11, 1, 7, 0, tzinfo=timezone.utc)
+
+
+def test_enabled_and_due_checks(schedule_module):
+ """Validate disabled, not-due, and due schedule decisions."""
+ next_run = datetime(2026, 7, 15, 6, 0, tzinfo=timezone.utc)
+ settings = {
+ "control_center_auto_refresh_enabled": True,
+ "control_center_auto_refresh_next_run": next_run.isoformat(),
+ }
+
+ assert not schedule_module.is_control_center_auto_refresh_due(
+ settings,
+ current_time=datetime(2026, 7, 15, 5, 59, tzinfo=timezone.utc),
+ )
+ assert schedule_module.is_control_center_auto_refresh_due(
+ settings,
+ current_time=next_run,
+ )
+
+ settings["control_center_auto_refresh_enabled"] = False
+ assert not schedule_module.is_control_center_auto_refresh_due(
+ settings,
+ current_time=datetime(2026, 7, 15, 6, 1, tzinfo=timezone.utc),
+ )
+
+
+def test_integration_wiring():
+ """Validate defaults, persistence, scheduler, API, and browser-local rendering."""
+ settings_source = SETTINGS_FILE.read_text(encoding="utf-8")
+ background_source = BACKGROUND_TASKS_FILE.read_text(encoding="utf-8")
+ admin_route_source = ADMIN_SETTINGS_ROUTE_FILE.read_text(encoding="utf-8")
+ control_center_route_source = CONTROL_CENTER_ROUTE_FILE.read_text(encoding="utf-8")
+ template_source = ADMIN_TEMPLATE_FILE.read_text(encoding="utf-8")
+ javascript_source = CONTROL_CENTER_JS_FILE.read_text(encoding="utf-8")
+
+ expected_settings = [
+ "'control_center_auto_refresh_enabled': True",
+ "'control_center_auto_refresh_time': '02:00'",
+ "'control_center_auto_refresh_timezone': 'America/New_York'",
+ "legacy_control_center_schedule",
+ "merged['control_center_auto_refresh_timezone'] = 'UTC'",
]
- for snippet in template_snippets:
- assert_contains(template_source, snippet, "admin template schedule control")
-
+ for snippet in expected_settings:
+ assert_contains(settings_source, snippet, "Control Center schedule default or migration")
-def test_background_scheduler(background_source):
- """Validate the background scheduler runs Control Center refresh when due."""
- expected_snippets = [
+ expected_background = [
"def check_control_center_auto_refresh_once",
"acquire_distributed_task_lock('control_center_auto_refresh'",
"execute_control_center_refresh(manual_execution=False)",
- "def run_control_center_auto_refresh_loop",
- "('Control Center auto-refresh background task started.', run_control_center_auto_refresh_loop)",
+ "'control_center_auto_refresh_timezone': schedule['timezone']",
+ "run_control_center_auto_refresh_loop",
]
- for snippet in expected_snippets:
- assert_contains(background_source, snippet, "background auto-refresh scheduler")
+ for snippet in expected_background:
+ assert_contains(background_source, snippet, "background scheduler integration")
+ expected_admin = [
+ "incoming_control_center_auto_refresh_timezone",
+ "'control_center_auto_refresh_timezone': control_center_auto_refresh_schedule['timezone']",
+ "calculate_next_control_center_auto_refresh_run",
+ ]
+ for snippet in expected_admin:
+ assert_contains(admin_route_source, snippet, "admin schedule persistence")
-def test_refresh_status_response(route_source):
- """Validate the refresh-status endpoint exposes schedule metadata."""
- expected_snippets = [
+ expected_status = [
"'auto_refresh_enabled': auto_refresh_enabled",
"'auto_refresh_time': auto_refresh_schedule['time']",
- "'auto_refresh_hour_formatted': f\"{auto_refresh_schedule['hour']:02d}:{auto_refresh_schedule['minute']:02d} UTC\"",
- "'auto_refresh_next_run_formatted': None if not auto_refresh_next_run_datetime",
+ "'auto_refresh_timezone': auto_refresh_schedule['timezone']",
+ "'auto_refresh_next_run_utc':",
]
- for snippet in expected_snippets:
- assert_contains(route_source, snippet, "refresh status schedule field")
-
-
-def run_all_tests():
- """Run all source-level Control Center auto-refresh checks."""
- print("Testing Control Center auto-refresh scheduling source changes...")
-
- current_version = get_version()
- if current_version != "0.241.026":
- raise AssertionError(f"Expected version 0.241.026, found {current_version}")
-
- settings_source = SETTINGS_FILE.read_text(encoding="utf-8")
- control_center_source = CONTROL_CENTER_FUNCTIONS_FILE.read_text(encoding="utf-8")
- background_source = BACKGROUND_TASKS_FILE.read_text(encoding="utf-8")
- admin_route_source = ADMIN_SETTINGS_ROUTE_FILE.read_text(encoding="utf-8")
- control_center_route_source = CONTROL_CENTER_ROUTE_FILE.read_text(encoding="utf-8")
- template_source = ADMIN_TEMPLATE_FILE.read_text(encoding="utf-8")
-
- test_default_settings(settings_source)
- print("Default settings checks passed")
+ for snippet in expected_status:
+ assert_contains(control_center_route_source, snippet, "refresh status response")
+
+ expected_ui = [
+ 'value="{{ settings.control_center_auto_refresh_time or \'02:00\' }}"',
+ 'id="control_center_auto_refresh_timezone"',
+ 'id="control-center-auto-refresh-viewer-timezone"',
+ "displayControlCenterAutoRefreshLocalTime",
+ "Intl.DateTimeFormat().resolvedOptions().timeZone",
+ ]
+ combined_ui_source = f"{template_source}\n{javascript_source}"
+ for snippet in expected_ui:
+ assert_contains(combined_ui_source, snippet, "browser-local schedule UI")
- test_schedule_helpers(control_center_source)
- print("Schedule helper checks passed")
- test_admin_settings_form(admin_route_source, template_source)
- print("Admin settings checks passed")
+def test_version():
+ """Validate the application version for this update."""
+ config_source = CONFIG_FILE.read_text(encoding="utf-8")
+ version_match = re.search(r'VERSION = "([^"]+)"', config_source)
+ if not version_match:
+ raise AssertionError("Could not find VERSION in config.py")
+ assert version_match.group(1) == "0.250.102"
- test_background_scheduler(background_source)
- print("Background scheduler checks passed")
- test_refresh_status_response(control_center_route_source)
- print("Refresh status checks passed")
+def run_all_tests():
+ """Run all Control Center auto-refresh schedule checks."""
+ schedule_module = load_control_center_module()
+ tests = [
+ lambda: test_default_schedule(schedule_module),
+ lambda: test_dst_aware_utc_next_runs(schedule_module),
+ lambda: test_dst_transition_days(schedule_module),
+ lambda: test_enabled_and_due_checks(schedule_module),
+ test_integration_wiring,
+ test_version,
+ ]
+ for test in tests:
+ test()
print("All Control Center auto-refresh schedule checks passed")
return True
@@ -148,4 +246,4 @@ def run_all_tests():
if __name__ == "__main__":
success = run_all_tests()
- sys.exit(0 if success else 1)
\ No newline at end of file
+ sys.exit(0 if success else 1)
diff --git a/ui_tests/test_admin_settings_control_center_auto_refresh.py b/ui_tests/test_admin_settings_control_center_auto_refresh.py
index 0cc5d691a..d15829f24 100644
--- a/ui_tests/test_admin_settings_control_center_auto_refresh.py
+++ b/ui_tests/test_admin_settings_control_center_auto_refresh.py
@@ -1,11 +1,12 @@
# test_admin_settings_control_center_auto_refresh.py
"""
UI test for Control Center auto-refresh admin settings.
-Version: 0.241.026
+Version: 0.250.102
Implemented in: 0.241.026
+Updated in: 0.250.102
-This test ensures the admin settings page exposes the daily UTC Control Center
-auto-refresh schedule controls with the enabled 06:00 default.
+This test ensures the admin settings page exposes the daily timezone-aware
+Control Center auto-refresh controls with the enabled 02:00 Eastern default.
"""
import os
@@ -48,9 +49,13 @@ def test_admin_settings_control_center_auto_refresh_controls(playwright):
auto_refresh_toggle = page.locator("#control_center_auto_refresh_enabled")
auto_refresh_time = page.locator("#control_center_auto_refresh_time")
+ auto_refresh_timezone = page.locator("#control_center_auto_refresh_timezone")
+ viewer_timezone = page.locator("#control-center-auto-refresh-viewer-timezone")
expect(auto_refresh_toggle).to_be_checked()
expect(auto_refresh_time).to_be_visible()
- expect(auto_refresh_time).to_have_value("06:00")
+ expect(auto_refresh_time).to_have_value("02:00")
+ expect(auto_refresh_timezone).to_have_value("America/New_York")
+ expect(viewer_timezone).not_to_have_text("local time")
auto_refresh_toggle.uncheck()
expect(page.locator("#control-center-auto-refresh-inputs")).to_have_class(