add report_date parameter that allows user to specify summary month

api/institutions/views.py

@@ -1,3 +1,4 @@
+from datetime import datetime
 from django.db.models import F
 from rest_framework import generics
 from rest_framework import permissions as drf_permissions
@@ -13,6 +14,7 @@
 from osf.models import OSFUser, Node, Institution, Registration
 from osf.metrics import UserInstitutionProjectCounts
 from osf.metrics.reports import InstitutionalUserReport, InstitutionMonthlySummaryReport
+from osf.metrics.utils import YearMonth
 from osf.utils import permissions as osf_permissions
 
 from api.base import permissions as base_permissions
@@ -612,7 +614,18 @@ def get_object(self):
             return object
 
     def get_default_search(self):
-        _yearmonth = InstitutionMonthlySummaryReport.most_recent_yearmonth()
+        report_date_str = self.request.query_params.get('report_date')
+        _yearmonth = None
+        if report_date_str:
+            try:
+                _yearmonth = YearMonth.from_str(report_date_str)
+            except ValueError:
+                _yearmonth = None
+        print(_yearmonth)
+
+        if not _yearmonth:
+            _yearmonth = InstitutionMonthlySummaryReport.most_recent_yearmonth()
+
         if _yearmonth is None:
             return None
         return (

api_tests/institutions/views/test_institution_summary_metrics.py

@@ -114,6 +114,18 @@ def institution(self):
     def rando(self):
         return AuthUserFactory()
 
+    @pytest.fixture()
+    def user(self):
+        return AuthUserFactory()
+
+    @pytest.fixture()
+    def admin(self, institution):
+        user = AuthUserFactory()
+        group = institution.get_group('institutional_admins')
+        group.user_set.add(user)
+        group.save()
+        return user
+
     @pytest.fixture()
     def institutional_admin(self, institution):
         admin_user = AuthUserFactory()
@@ -265,6 +277,74 @@ def test_get_report_with_multiple_months_and_institutions(
         assert attributes['monthly_logged_in_user_count'] == 220
         assert attributes['monthly_active_user_count'] == 200
 
+    def test_get_with_valid_report_date(self, app, url, institution, admin):
+        _summary_report_factory(
+            '2018-02',
+            institution,
+            user_count=4133,
+        )
+        _summary_report_factory(
+            '2024-08',
+            institution,
+            user_count=0,
+        )
+        _summary_report_factory(
+            '2024-09',
+            institution,
+            user_count=999,
+
+        )
+
+        resp = app.get(f'{url}?report_date=2024-08', auth=admin.auth)
+        assert resp.status_code == 200
+
+        attributes = resp.json['data']['attributes']
+        assert attributes['user_count'] == 0
+
+        resp = app.get(f'{url}?report_date=2018-02', auth=admin.auth)
+        assert resp.status_code == 200
+
+        attributes = resp.json['data']['attributes']
+        assert attributes['user_count'] == 4133
+
+    def test_get_with_invalid_report_date(self, app, url, institution, admin):
+        _summary_report_factory(
+            '2024-08',
+            institution,
+            user_count=0,
+        )
+        _summary_report_factory(
+            '2024-09',
+            institution,
+            user_count=999,
+        )
+
+        # Request with an invalid report_date format
+        resp = app.get(f'{url}?report_date=invalid-date', auth=admin.auth)
+        assert resp.status_code == 200
+
+        # Verify it defaults to the most recent report data
+        attributes = resp.json['data']['attributes']
+        assert attributes['user_count'] == 999
+
+    def test_get_without_report_date_uses_most_recent(self, app, url, institution, admin):
+        _summary_report_factory(
+            '2024-08',
+            institution,
+            user_count=0,
+        )
+        _summary_report_factory(
+            '2024-09',
+            institution,
+            user_count=999,
+        )
+
+        resp = app.get(url, auth=admin.auth)
+        assert resp.status_code == 200
+
+        attributes = resp.json['data']['attributes']
+        assert attributes['user_count'] == 999
+
 
 def _summary_report_factory(yearmonth, institution, **kwargs):
     report = InstitutionMonthlySummaryReport(