Merge pull request #583 from openedx/ammar/filter-engagement-data-by-group-uuid

feat: filter engagement data by group uuid

Author: muhammad-ammar

CHANGELOG.rst

@@ -15,6 +15,10 @@ Unreleased
 ----------
 
 =========================
+[10.13.0] - 2025-04-11
+---------------------
+  * feat: Support filtering of engagement API by group_uuid
+
 [10.12.0] - 2025-04-09
 ---------------------
   * feat: Added the ability to filter enrollments by group_uuid in the enterprise completions API

enterprise_data/__init__.py

@@ -2,4 +2,4 @@
 Enterprise data api application. This Django app exposes API endpoints used by enterprises.
 """
 
-__version__ = "10.12.0"
+__version__ = "10.13.0"

enterprise_data/admin_analytics/database/filters/__init__.py

@@ -3,4 +3,5 @@
 """
 
 from .fact_completion_admin_dash import FactCompletionAdminDashFilters
+from .fact_engagement_admin_dash import FactEngagementAdminDashFilters
 from .fact_enrollment_admin_dash import FactEnrollmentAdminDashFilters

enterprise_data/admin_analytics/database/filters/fact_completion_admin_dash.py

@@ -2,28 +2,14 @@
 Query filters for enrollments table.
 """
 from enterprise_data.admin_analytics.database.filters.base import BaseFilter
-from enterprise_data.admin_analytics.database.query_filters import BetweenQueryFilter, EqualQueryFilter
+from enterprise_data.admin_analytics.database.filters.mixins import CommonFiltersMixin
+from enterprise_data.admin_analytics.database.query_filters import EqualQueryFilter
 
 
-class FactCompletionAdminDashFilters(BaseFilter):
+class FactCompletionAdminDashFilters(CommonFiltersMixin, BaseFilter):
     """
     Query filters for completions data in enrollments table.
     """
-    @staticmethod
-    def passed_date_range_filter(
-            start_date_params_key: str, end_date_params_key: str
-    ) -> BetweenQueryFilter:
-        """
-        Filter by passed date to be in the given range.
-
-        Arguments:
-            start_date_params_key (str): The start date key against which value will be passed in the query.
-            end_date_params_key (str): The end date key against which value will be passed in the query.
-        """
-        return BetweenQueryFilter(
-            column='passed_date',
-            range_placeholders=(start_date_params_key, end_date_params_key),
-        )
 
     @staticmethod
     def has_passed_filter() -> EqualQueryFilter:

enterprise_data/admin_analytics/database/filters/fact_engagement_admin_dash.py

@@ -0,0 +1,11 @@
+"""
+Query filters for engagments data.
+"""
+from enterprise_data.admin_analytics.database.filters.base import BaseFilter
+from enterprise_data.admin_analytics.database.filters.mixins import CommonFiltersMixin
+
+
+class FactEngagementAdminDashFilters(CommonFiltersMixin, BaseFilter):
+    """
+    Query filters for engagments data.
+    """

enterprise_data/admin_analytics/database/filters/fact_enrollment_admin_dash.py

@@ -2,50 +2,10 @@
 Query filters for enrollments table.
 """
 from enterprise_data.admin_analytics.database.filters.base import BaseFilter
-from enterprise_data.admin_analytics.database.query_filters import BetweenQueryFilter, EqualQueryFilter, INQueryFilter
+from enterprise_data.admin_analytics.database.filters.mixins import CommonFiltersMixin
 
 
-class FactEnrollmentAdminDashFilters(BaseFilter):
+class FactEnrollmentAdminDashFilters(CommonFiltersMixin, BaseFilter):
     """
     Query filters for enrollments table.
     """
-    @staticmethod
-    def enterprise_customer_uuid_filter(enterprise_customer_uuid_params_key: str) -> EqualQueryFilter:
-        """
-        Filter by enterprise customer uuid.
-
-        Arguments:
-            enterprise_customer_uuid_params_key: The key against which value will be passed in the query.
-        """
-        return EqualQueryFilter(
-            column='enterprise_customer_uuid',
-            value_placeholder=enterprise_customer_uuid_params_key,
-        )
-
-    @staticmethod
-    def enterprise_enrollment_date_range_filter(
-            start_date_params_key: str, end_date_params_key: str
-    ) -> BetweenQueryFilter:
-        """
-        Filter by enrollment date to be in the given range.
-
-        Arguments:
-            start_date_params_key (str): The start date key against which value will be passed in the query.
-            end_date_params_key (str): The end date key against which value will be passed in the query.
-        """
-        return BetweenQueryFilter(
-            column='enterprise_enrollment_date',
-            range_placeholders=(start_date_params_key, end_date_params_key),
-        )
-
-    @staticmethod
-    def enterprise_user_id_in_filter(
-            enterprise_user_id_param_keys: list,
-    ) -> INQueryFilter:
-        """
-        Filter by enterprise user id.
-        """
-        return INQueryFilter(
-            column='enterprise_user_id',
-            values_placeholders=enterprise_user_id_param_keys
-        )

enterprise_data/admin_analytics/database/filters/mixins.py

@@ -0,0 +1,84 @@
+"""
+Common query filters for all tables.
+"""
+from logging import getLogger
+from typing import Optional, Tuple
+from uuid import UUID
+
+from enterprise_data.admin_analytics.database.filters.base import BaseFilter
+from enterprise_data.admin_analytics.database.query_filters import BetweenQueryFilter, EqualQueryFilter, INQueryFilter
+from enterprise_data.clients import EnterpriseApiClient
+from enterprise_data.exceptions import EnterpriseApiClientException
+
+LOGGER = getLogger(__name__)
+
+
+class CommonFiltersMixin(BaseFilter):
+    """
+    Common filters.
+    """
+    @staticmethod
+    def enterprise_customer_uuid_filter(enterprise_customer_uuid_params_key: str) -> EqualQueryFilter:
+        """
+        Filter by enterprise customer uuid.
+
+        Arguments:
+            enterprise_customer_uuid_params_key: The key against which value will be passed in the query.
+        """
+        return EqualQueryFilter(
+            column='enterprise_customer_uuid',
+            value_placeholder=enterprise_customer_uuid_params_key,
+        )
+
+    @staticmethod
+    def date_range_filter(
+        column: str,
+        start_date_params_key: str,
+        end_date_params_key: str
+    ) -> BetweenQueryFilter:
+        """
+        Filter by a table column to be in the given date range.
+
+        Arguments:
+            column (str): The table column name to filter on.
+            start_date_params_key (str): The start date key against which value will be passed in the query.
+            end_date_params_key (str): The end date key against which value will be passed in the query.
+        """
+        return BetweenQueryFilter(
+            column=column,
+            range_placeholders=(start_date_params_key, end_date_params_key),
+        )
+
+    def enterprise_user_query_filter(  # pylint: disable=inconsistent-return-statements
+        self,
+        group_uuid: Optional[UUID],
+        enterprise_customer_uuid: UUID
+    ) -> Optional[Tuple[INQueryFilter, dict]]:
+        """
+        Get the query filter to filter enrollments for enterprise users in the given group.
+
+        Arguments:
+            group_uuid (UUID): The UUID of the group.
+            enterprise_customer_uuid (UUID): The UUID of the enterprise customer.
+
+        Returns:
+            (INQueryFilter | None): The query filter to filter enrollments for enterprise users in the given group.
+        """
+        if not group_uuid:
+            return None
+
+        try:
+            learners_in_group = EnterpriseApiClient.get_enterprise_user_ids_in_group(group_uuid)
+        except EnterpriseApiClientException:
+            LOGGER.exception(
+                "Failed to get learners in group [%s] for enterprise [%s]",
+                group_uuid,
+                enterprise_customer_uuid,
+            )
+        else:
+            params = {f'eu_{i}': i for i in learners_in_group}
+            enterprise_user_id_in_filter = INQueryFilter(
+                column='enterprise_user_id',
+                values_placeholders=list(params.keys()),
+            )
+            return enterprise_user_id_in_filter, params

enterprise_data/admin_analytics/database/queries/fact_engagement_admin_dash.py

@@ -21,34 +21,32 @@ def get_learning_hours_and_daily_sessions_query():
         """
 
     @staticmethod
-    def get_engagement_count_query():
+    def get_engagement_count_query(query_filters):
         """
         Get the query to fetch the total number of engagements for an enterprise customer.
         """
-        return """
+        return f"""
             SELECT count(*)
             FROM fact_enrollment_engagement_day_admin_dash
-            WHERE enterprise_customer_uuid=%(enterprise_customer_uuid)s AND
-                activity_date BETWEEN %(start_date)s AND %(end_date)s;
+            WHERE {query_filters.to_sql()};
         """
 
     @staticmethod
-    def get_all_engagement_query():
+    def get_all_engagement_query(query_filters):
         """
         Get the query to fetch all engagement data.
         """
-        return """
+        return f"""
             SELECT
                 email, course_title, course_subject, enroll_type, activity_date,
                 learning_time_seconds/3600 as learning_time_hours
             FROM fact_enrollment_engagement_day_admin_dash
-            WHERE enterprise_customer_uuid=%(enterprise_customer_uuid)s AND
-                activity_date BETWEEN %(start_date)s AND %(end_date)s
+            WHERE {query_filters.to_sql()}
             ORDER BY activity_date DESC LIMIT %(limit)s OFFSET %(offset)s;
         """
 
     @staticmethod
-    def get_top_courses_by_engagement_query(record_count=10):
+    def get_top_courses_by_engagement_query(query_filters, record_count=10):
         """
         Get the query to fetch the learning time in hours by courses.
 
@@ -69,8 +67,7 @@ def get_top_courses_by_engagement_query(record_count=10):
                     (learning_time_seconds / 60.0 / 60.0) AS learning_time_hours,
                     activity_date
                 FROM fact_enrollment_engagement_day_admin_dash
-                WHERE enterprise_customer_uuid=%(enterprise_customer_uuid)s AND
-                activity_date BETWEEN %(start_date)s AND %(end_date)s
+                WHERE {query_filters.to_sql()}
             ),
             top_10_courses AS (
                 SELECT
@@ -94,7 +91,7 @@ def get_top_courses_by_engagement_query(record_count=10):
         """
 
     @staticmethod
-    def get_top_subjects_by_engagement_query(record_count=10):
+    def get_top_subjects_by_engagement_query(query_filters, record_count=10):
         """
         Get the query to fetch the learning time in hours by subjects.
 
@@ -114,8 +111,7 @@ def get_top_subjects_by_engagement_query(record_count=10):
                     (learning_time_seconds / 60.0 / 60.0) AS learning_time_hours,
                     activity_date
                 FROM fact_enrollment_engagement_day_admin_dash
-                WHERE enterprise_customer_uuid=%(enterprise_customer_uuid)s AND
-                activity_date BETWEEN %(start_date)s AND %(end_date)s
+                WHERE {query_filters.to_sql()}
             ),
             top_10_subjects AS (
                 SELECT
@@ -138,7 +134,7 @@ def get_top_subjects_by_engagement_query(record_count=10):
         """
 
     @staticmethod
-    def get_engagement_time_series_data_query():
+    def get_engagement_time_series_data_query(query_filters):
         """
         Get the query to fetch the completion time series data.
 
@@ -147,11 +143,10 @@ def get_engagement_time_series_data_query():
         Returns:
             (str): Query to fetch the completion time series data.
         """
-        return """
+        return f"""
             SELECT activity_date, enroll_type, SUM(learning_time_seconds)/3600 as learning_time_hours
             FROM fact_enrollment_engagement_day_admin_dash
-            WHERE enterprise_customer_uuid=%(enterprise_customer_uuid)s AND
-                activity_date BETWEEN %(start_date)s AND %(end_date)s
+            WHERE {query_filters.to_sql()}
             GROUP BY activity_date, enroll_type
             ORDER BY activity_date;
         """