edx-enterprise-data 10.12.0__tar.gz → 10.13.0__tar.gz

{edx_enterprise_data-10.12.0 → edx_enterprise_data-10.13.0}/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

{edx_enterprise_data-10.12.0/edx_enterprise_data.egg-info → edx_enterprise_data-10.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: edx-enterprise-data
-Version: 10.12.0
+Version: 10.13.0
 Summary: Enterprise Reporting
 Home-page: https://github.com/openedx/edx-enterprise-data
 Author: edX

{edx_enterprise_data-10.12.0 → edx_enterprise_data-10.13.0/edx_enterprise_data.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: edx-enterprise-data
-Version: 10.12.0
+Version: 10.13.0
 Summary: Enterprise Reporting
 Home-page: https://github.com/openedx/edx-enterprise-data
 Author: edX

{edx_enterprise_data-10.12.0 → edx_enterprise_data-10.13.0}/edx_enterprise_data.egg-info/SOURCES.txt

@@ -29,7 +29,9 @@ enterprise_data/admin_analytics/database/utils.py
 enterprise_data/admin_analytics/database/filters/__init__.py
 enterprise_data/admin_analytics/database/filters/base.py
 enterprise_data/admin_analytics/database/filters/fact_completion_admin_dash.py
+enterprise_data/admin_analytics/database/filters/fact_engagement_admin_dash.py
 enterprise_data/admin_analytics/database/filters/fact_enrollment_admin_dash.py
+enterprise_data/admin_analytics/database/filters/mixins.py
 enterprise_data/admin_analytics/database/queries/__init__.py
 enterprise_data/admin_analytics/database/queries/fact_engagement_admin_dash.py
 enterprise_data/admin_analytics/database/queries/fact_enrollment_admin_dash.py

{edx_enterprise_data-10.12.0 → edx_enterprise_data-10.13.0}/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"

{edx_enterprise_data-10.12.0 → edx_enterprise_data-10.13.0}/enterprise_data/admin_analytics/database/filters/__init__.py

@@ -3,4 +3,5 @@ Query Filters for database tables.
 """
 
 from .fact_completion_admin_dash import FactCompletionAdminDashFilters
+from .fact_engagement_admin_dash import FactEngagementAdminDashFilters
 from .fact_enrollment_admin_dash import FactEnrollmentAdminDashFilters

edx_enterprise_data-10.13.0/enterprise_data/admin_analytics/database/filters/fact_completion_admin_dash.py

@@ -0,0 +1,22 @@
+"""
+Query filters for enrollments table.
+"""
+from enterprise_data.admin_analytics.database.filters.base import BaseFilter
+from enterprise_data.admin_analytics.database.filters.mixins import CommonFiltersMixin
+from enterprise_data.admin_analytics.database.query_filters import EqualQueryFilter
+
+
+class FactCompletionAdminDashFilters(CommonFiltersMixin, BaseFilter):
+    """
+    Query filters for completions data in enrollments table.
+    """
+
+    @staticmethod
+    def has_passed_filter() -> EqualQueryFilter:
+        """
+        Filter by has passed with fixed value 1.
+        """
+        return EqualQueryFilter(
+            column='has_passed',
+            value=1
+        )

edx_enterprise_data-10.13.0/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.
+    """

edx_enterprise_data-10.13.0/enterprise_data/admin_analytics/database/filters/fact_enrollment_admin_dash.py

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

edx_enterprise_data-10.13.0/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

{edx_enterprise_data-10.12.0 → edx_enterprise_data-10.13.0}/enterprise_data/admin_analytics/database/queries/fact_engagement_admin_dash.py

@@ -21,34 +21,32 @@ class FactEngagementAdminDashQueries:
         """
 
     @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 @@ class FactEngagementAdminDashQueries:
                     (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 @@ class FactEngagementAdminDashQueries:
         """
 
     @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 @@ class FactEngagementAdminDashQueries:
                     (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 @@ class FactEngagementAdminDashQueries:
         """
 
     @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 @@ class FactEngagementAdminDashQueries:
         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;
         """

{edx_enterprise_data-10.12.0 → edx_enterprise_data-10.13.0}/enterprise_data/admin_analytics/database/tables/fact_engagement_admin_dash.py

@@ -2,12 +2,15 @@
 Module for interacting with the fact_enrollment_engagement_day_admin_dash table.
 """
 from datetime import date
+from typing import Optional, Tuple
 from uuid import UUID
 
 from enterprise_data.cache.decorators import cache_it
 from enterprise_data.utils import find_first
 
+from ..filters import FactEngagementAdminDashFilters
 from ..queries import FactEngagementAdminDashQueries
+from ..query_filters import QueryFilters
 from ..utils import run_query
 from .base import BaseTable
 
@@ -19,6 +22,43 @@ class FactEngagementAdminDashTable(BaseTable):
     Class for communicating with the fact_enrollment_engagement_day_admin_dash table.
     """
     queries = FactEngagementAdminDashQueries()
+    engagement_filters = FactEngagementAdminDashFilters()
+
+    def __get_common_query_filters_for_engagement(
+            self, enterprise_customer_uuid: UUID,
+            group_uuid: Optional[UUID],
+            start_date: date,
+            end_date: date,
+    ) -> Tuple[QueryFilters, dict]:
+        """
+        Utility method to get query filters common in most usages below.
+        This will return a tuple containing the query filters list and the dictionary of query parameters that
+        will be used in the query.
+        It will contain the following query filters.
+            1. enterprise_customer_uuid filter to filter records for an enterprise customer.
+            2. enrollment_date range filter to filter records by enrollment date.
+            3. group_uuid filter to filter records for learners who belong to the given group.
+        """
+        query_filters = QueryFilters([
+            self.engagement_filters.enterprise_customer_uuid_filter('enterprise_customer_uuid'),
+            self.engagement_filters.date_range_filter('activity_date', 'start_date', 'end_date'),
+        ])
+        params = {
+            'enterprise_customer_uuid': enterprise_customer_uuid,
+            'start_date': start_date,
+            'end_date': end_date,
+        }
+
+        response = self.engagement_filters.enterprise_user_query_filter(
+            group_uuid,
+            enterprise_customer_uuid
+        )
+        if response is not None:
+            enterprise_user_id_in_filter, enterprise_user_id_params = response
+            query_filters.append(enterprise_user_id_in_filter)
+            params.update(enterprise_user_id_params)
+
+        return query_filters, params
 
     @cache_it()
     def get_learning_hours_and_daily_sessions(self, enterprise_customer_uuid: UUID, start_date: date, end_date: date):
@@ -47,7 +87,13 @@ class FactEngagementAdminDashTable(BaseTable):
         return tuple(results[0])
 
     @cache_it()
-    def get_engagement_count(self, enterprise_customer_uuid: UUID, start_date: date, end_date: date):
+    def get_engagement_count(
+        self,
+        enterprise_customer_uuid: UUID,
+        group_uuid: Optional[UUID],
+        start_date: date,
+        end_date: date
+    ):
         """
         Get the total number of engagements for the given enterprise customer.
 
@@ -59,13 +105,13 @@ class FactEngagementAdminDashTable(BaseTable):
         Returns:
             int: The total number of engagements.
         """
+        query_filters, query_filter_params = self.__get_common_query_filters_for_engagement(
+            enterprise_customer_uuid, group_uuid, start_date, end_date
+        )
+
         results = run_query(
-            query=self.queries.get_engagement_count_query(),
-            params={
-                'enterprise_customer_uuid': enterprise_customer_uuid,
-                'start_date': start_date,
-                'end_date': end_date,
-            }
+            query=self.queries.get_engagement_count_query(query_filters),
+            params=query_filter_params,
         )
         if not results:
             return 0
@@ -73,13 +119,20 @@ class FactEngagementAdminDashTable(BaseTable):
 
     @cache_it()
     def get_all_engagements(
-            self, enterprise_customer_uuid: UUID, start_date: date, end_date: date, limit: int, offset: int
+        self,
+        enterprise_customer_uuid: UUID,
+        group_uuid: Optional[UUID],
+        start_date: date,
+        end_date: date,
+        limit: int,
+        offset: int
     ):
         """
         Get all engagement data for the given enterprise customer.
 
         Arguments:
             enterprise_customer_uuid (UUID): The UUID of the enterprise customer.
+            group_uuid (UUID): The UUID of a group.
             start_date (date): The start date.
             end_date (date): The end date.
             limit (int): The maximum number of records to return.
@@ -88,12 +141,14 @@ class FactEngagementAdminDashTable(BaseTable):
         Returns:
             list<dict>: A list of dictionaries containing the engagement data.
         """
+        query_filters, query_filter_params = self.__get_common_query_filters_for_engagement(
+            enterprise_customer_uuid, group_uuid, start_date, end_date
+        )
+
         return run_query(
-            query=self.queries.get_all_engagement_query(),
+            query=self.queries.get_all_engagement_query(query_filters),
             params={
-                'enterprise_customer_uuid': enterprise_customer_uuid,
-                'start_date': start_date,
-                'end_date': end_date,
+                **query_filter_params,
                 'limit': limit,
                 'offset': offset,
             },
@@ -101,7 +156,13 @@ class FactEngagementAdminDashTable(BaseTable):
         )
 
     @cache_it()
-    def get_top_courses_by_engagement(self, enterprise_customer_uuid: UUID, start_date: date, end_date: date):
+    def get_top_courses_by_engagement(
+        self,
+        enterprise_customer_uuid: UUID,
+        group_uuid: Optional[UUID],
+        start_date: date,
+        end_date: date
+    ):
         """
         Get the top courses by user engagement for the given enterprise customer.
 
@@ -113,18 +174,23 @@ class FactEngagementAdminDashTable(BaseTable):
         Returns:
             list<dict>: A list of dictionaries containing the course data.
         """
+        query_filters, query_filter_params = self.__get_common_query_filters_for_engagement(
+            enterprise_customer_uuid, group_uuid, start_date, end_date
+        )
         return run_query(
-            query=self.queries.get_top_courses_by_engagement_query(),
-            params={
-                'enterprise_customer_uuid': enterprise_customer_uuid,
-                'start_date': start_date,
-                'end_date': end_date,
-            },
+            query=self.queries.get_top_courses_by_engagement_query(query_filters),
+            params=query_filter_params,
             as_dict=True,
         )
 
     @cache_it()
-    def get_top_subjects_by_engagement(self, enterprise_customer_uuid: UUID, start_date: date, end_date: date):
+    def get_top_subjects_by_engagement(
+        self,
+        enterprise_customer_uuid: UUID,
+        group_uuid: Optional[UUID],
+        start_date: date,
+        end_date: date
+    ):
         """
         Get the top subjects by user engagement for the given enterprise customer.
 
@@ -136,18 +202,23 @@ class FactEngagementAdminDashTable(BaseTable):
         Returns:
             list<dict>: A list of dictionaries containing the subject data.
         """
+        query_filters, query_filter_params = self.__get_common_query_filters_for_engagement(
+            enterprise_customer_uuid, group_uuid, start_date, end_date
+        )
         return run_query(
-            query=self.queries.get_top_subjects_by_engagement_query(),
-            params={
-                'enterprise_customer_uuid': enterprise_customer_uuid,
-                'start_date': start_date,
-                'end_date': end_date,
-            },
+            query=self.queries.get_top_subjects_by_engagement_query(query_filters),
+            params=query_filter_params,
             as_dict=True,
         )
 
     @cache_it()
-    def get_engagement_time_series_data(self, enterprise_customer_uuid: UUID, start_date: date, end_date: date):
+    def get_engagement_time_series_data(
+        self,
+        enterprise_customer_uuid: UUID,
+        group_uuid: Optional[UUID],
+        start_date: date,
+        end_date: date
+    ):
         """
         Get the engagement time series data.
 
@@ -159,13 +230,12 @@ class FactEngagementAdminDashTable(BaseTable):
         Returns:
             list<dict>: A list of dictionaries containing the engagement time series data.
         """
+        query_filters, query_filter_params = self.__get_common_query_filters_for_engagement(
+            enterprise_customer_uuid, group_uuid, start_date, end_date
+        )
         return run_query(
-            query=self.queries.get_engagement_time_series_data_query(),
-            params={
-                'enterprise_customer_uuid': enterprise_customer_uuid,
-                'start_date': start_date,
-                'end_date': end_date,
-            },
+            query=self.queries.get_engagement_time_series_data_query(query_filters),
+            params=query_filter_params,
             as_dict=True,
         )
 

{edx_enterprise_data-10.12.0 → edx_enterprise_data-10.13.0}/enterprise_data/admin_analytics/database/tables/fact_enrollment_admin_dash.py

@@ -2,60 +2,26 @@
 Module for interacting with the fact_enrollment_admin_dash table.
 """
 from datetime import date, datetime
-from logging import getLogger
 from typing import Optional, Tuple
 from uuid import UUID
 
 from enterprise_data.cache.decorators import cache_it
-from enterprise_data.clients import EnterpriseApiClient
-from enterprise_data.exceptions import EnterpriseApiClientException
 
 from ..filters import FactCompletionAdminDashFilters, FactEnrollmentAdminDashFilters
 from ..queries import FactEnrollmentAdminDashQueries
-from ..query_filters import INQueryFilter, QueryFilters
+from ..query_filters import QueryFilters
 from ..utils import run_query
 from .base import BaseTable
 
-LOGGER = getLogger(__name__)
-
 
 class FactEnrollmentAdminDashTable(BaseTable):
     """
     Class for communicating with the fact_enrollment_admin_dash table.
     """
     queries = FactEnrollmentAdminDashQueries()
-    filters = FactEnrollmentAdminDashFilters()
+    enrollment_filters = FactEnrollmentAdminDashFilters()
     completion_filters = FactCompletionAdminDashFilters()
 
-    def __get_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}': enterprise_user_id for i, enterprise_user_id in enumerate(learners_in_group)}
-            return self.filters.enterprise_user_id_in_filter(list(params.keys())), params
-
     def __get_common_query_filters(
             self, enterprise_customer_uuid: UUID,
             group_uuid: Optional[UUID],
@@ -74,8 +40,8 @@ class FactEnrollmentAdminDashTable(BaseTable):
             3. group_uuid filter to filter records for learners who belong to the given group.
         """
         query_filters = QueryFilters([
-            self.filters.enterprise_customer_uuid_filter('enterprise_customer_uuid'),
-            self.filters.enterprise_enrollment_date_range_filter('start_date', 'end_date'),
+            self.enrollment_filters.enterprise_customer_uuid_filter('enterprise_customer_uuid'),
+            self.enrollment_filters.date_range_filter('enterprise_enrollment_date', 'start_date', 'end_date'),
         ])
         params = {
             'enterprise_customer_uuid': enterprise_customer_uuid,
@@ -83,7 +49,7 @@ class FactEnrollmentAdminDashTable(BaseTable):
             'end_date': end_date,
         }
 
-        response = self.__get_enterprise_user_query_filter(
+        response = self.enrollment_filters.enterprise_user_query_filter(
             group_uuid, enterprise_customer_uuid
         )
         if response is not None:
@@ -112,8 +78,8 @@ class FactEnrollmentAdminDashTable(BaseTable):
             4. has_passed filter to filter records for successful completions.
         """
         query_filters = QueryFilters([
-            self.filters.enterprise_customer_uuid_filter('enterprise_customer_uuid'),
-            self.completion_filters.passed_date_range_filter('start_date', 'end_date'),
+            self.completion_filters.enterprise_customer_uuid_filter('enterprise_customer_uuid'),
+            self.completion_filters.date_range_filter('passed_date', 'start_date', 'end_date'),
             self.completion_filters.has_passed_filter(),
         ])
         params = {
@@ -122,7 +88,7 @@ class FactEnrollmentAdminDashTable(BaseTable):
             'end_date': end_date,
         }
 
-        response = self.__get_enterprise_user_query_filter(
+        response = self.completion_filters.enterprise_user_query_filter(
             group_uuid, enterprise_customer_uuid
         )
         if response is not None: