From 745218f31ed7ae09c664ad0f83fa807ab4341e29 Mon Sep 17 00:00:00 2001 From: Greg Price Date: Wed, 1 Oct 2014 16:23:38 -0400 Subject: [PATCH] Add documentation for cohort events --- .../internal_data_formats/.#tracking_logs.rst | 1 - .../internal_data_formats/event_list.rst | 12 +- .../internal_data_formats/tracking_logs.rst | 185 +++++++++++++++++- 3 files changed, 195 insertions(+), 3 deletions(-) delete mode 120000 docs/en_us/data/source/internal_data_formats/.#tracking_logs.rst diff --git a/docs/en_us/data/source/internal_data_formats/.#tracking_logs.rst b/docs/en_us/data/source/internal_data_formats/.#tracking_logs.rst deleted file mode 120000 index b017637239..0000000000 --- a/docs/en_us/data/source/internal_data_formats/.#tracking_logs.rst +++ /dev/null @@ -1 +0,0 @@ -gprice@gprice-mbp.local.3450 \ No newline at end of file diff --git a/docs/en_us/data/source/internal_data_formats/event_list.rst b/docs/en_us/data/source/internal_data_formats/event_list.rst index bc1d6c0499..7b742b72ed 100644 --- a/docs/en_us/data/source/internal_data_formats/event_list.rst +++ b/docs/en_us/data/source/internal_data_formats/event_list.rst @@ -42,6 +42,16 @@ Alphabetical Event List - :ref:`Instructor_Event_Types` * - ``dump-grades-raw`` - :ref:`Instructor_Event_Types` + * - ``edx.cohort.created`` + - :ref:`student_cohort_events` + * - ``edx.cohort.creation_requested`` + - :ref:`instructor_cohort_events` + * - ``edx.cohort.user_add_requested`` + - :ref:`instructor_cohort_events` + * - ``edx.cohort.user_added`` + - :ref:`student_cohort_events` + * - ``edx.cohort.user_removed`` + - :ref:`student_cohort_events` * - ``edx.course.enrollment.activated`` - :ref:`enrollment` and :ref:`instructor_enrollment` * - ``edx.course.enrollment.deactivated`` @@ -207,4 +217,4 @@ Alphabetical Event List .. * - ``problem_reset`` .. - :ref:`problem` .. * - ``show_transcript`` -.. - :ref:`video` \ No newline at end of file +.. - :ref:`video` diff --git a/docs/en_us/data/source/internal_data_formats/tracking_logs.rst b/docs/en_us/data/source/internal_data_formats/tracking_logs.rst index 58a9bafaf5..b501c43be1 100644 --- a/docs/en_us/data/source/internal_data_formats/tracking_logs.rst +++ b/docs/en_us/data/source/internal_data_formats/tracking_logs.rst @@ -301,6 +301,8 @@ outside the Instructor Dashboard. * :ref:`AB_Event_Types` +* :ref:`student_cohort_events` + * :ref:`ora` The descriptions that follow include what each event represents, the system @@ -1747,7 +1749,7 @@ After a user executes a text search in the navigation sidebar of the course **Event Source**: Server **History**: Added 16 May 2014. The ``corrected_text`` field was added 5 -Jun 2014. +Jun 2014. The ``group_id`` field was added 7 October 2014. ``event`` **Fields**: @@ -1761,6 +1763,15 @@ Jun 2014. * - ``query`` - string - The text entered into the search box by the user. + * - ``group_id`` + - integer + - The numeric ID of the cohort group to which the user's search is + restricted, or ``null`` if the search is not restricted in this way. In a + course with cohorts enabled, a student's searches will always be + restricted to the student's cohort group. Discussion Admins, Moderators, and + Community TAs in such a course can search all discussions + without specifying a cohort group, which leaves this field + ``null`, or they can specify a single cohort group to search. * - ``page`` - integer - Results are returned in sets of 20 per page. Identifies the page of @@ -2159,6 +2170,101 @@ the child module that was shown to the student. - string - ID of the module that displays to the student. +.. _student_cohort_events: + +========================== +Student Cohort Events +========================== + +``edx.cohort.created`` +---------------------------------- + +When a cohort group is created (either automatically, when a user is assigned to +the default cohort group or a cohort group included in the course's +``auto_cohort_groups`` setting, or manually, via the Instructor Dashboard), the +server emits an ``edx.cohort.created`` event. + +**Event Source**: Server + +**History** Added 7 Oct 2014. + +``event`` **Fields**: + +.. list-table:: + :widths: 15 15 60 + :header-rows: 1 + + * - Field + - Type + - Details + * - ``cohort_id`` + - integer + - The numeric ID of the cohort group. + * - ``cohort_name`` + - string + - The display name of the cohort group. + +``edx.cohort.user_added`` +---------------------------------- + +When a user is added to a cohort group (either automatically, when a user is +assigned to the default cohort group or a cohort group included in the course's +``auto_cohort_groups`` setting, or manually, via the Instructor Dashboard), the +server emits an ``edx.cohort.user_added`` event. + +**Event Source**: Server + +**History** Added 7 Oct 2014. + +``event`` **Fields**: + +.. list-table:: + :widths: 15 15 60 + :header-rows: 1 + + * - Field + - Type + - Details + * - ``user_id`` + - integer + - The numeric ID (from auth_user.id) of the added user. + * - ``cohort_id`` + - integer + - The numeric ID of the cohort group. + * - ``cohort_name`` + - string + - The display name of the cohort group. + +``edx.cohort.user_removed`` +---------------------------------- + +When a user is removed from a cohort group (by being assigned to a different +cohort group via the Instructor Dashboard), the server emits an +``edx.cohort.user_removed`` event. + +**Event Source**: Server + +**History** Added 7 Oct 2014. + +``event`` **Fields**: + +.. list-table:: + :widths: 15 15 60 + :header-rows: 1 + + * - Field + - Type + - Details + * - ``user_id`` + - integer + - The numeric ID (from auth_user.id) of the removed user. + * - ``cohort_id`` + - integer + - The numeric ID of the cohort group. + * - ``cohort_name`` + - string + - The display name of the cohort group. + .. _ora: ============================================ @@ -2593,5 +2699,82 @@ members also generate enrollment events. For details about the enrollment events, see :ref:`enrollment`. +.. _instructor_cohort_events: + +============================= +Instructor Cohort Events +============================= + +In addition to the cohort events that are generated when students are assigned +to cohort groups (which can happen automatically or manually via the Instructor +Dashboard; see :ref:`student_cohort_events`), actions by instructors and course +staff members generate additional events. + +``edx.cohort.creation_requested`` +---------------------------------- + +When an instructor or course staff member manually creates a cohort group via +the Instructor Dashboard, the server emits an ``edx.cohort.creation_requested`` +event. + +**Event Source**: Server + +**History** Added 7 Oct 2014. + +``event`` **Fields**: + +.. list-table:: + :widths: 15 15 60 + :header-rows: 1 + + * - Field + - Type + - Details + * - ``cohort_id`` + - integer + - The numeric ID of the cohort group. + * - ``cohort_name`` + - string + - The display name of the cohort group. + +``edx.cohort.user_add_requested`` +---------------------------------- + +When an instructor or course staff member adds a student to a cohort group via +the Instructor Dashboard, the server emits an ``edx.cohort.user_add_requested`` +event. + +**Event Source**: Server + +**History** Added 7 Oct 2014. + +``event`` **Fields**: + +.. list-table:: + :widths: 15 15 60 + :header-rows: 1 + + * - Field + - Type + - Details + * - ``user_id`` + - integer + - The numeric ID (from auth_user.id) of the added user. + * - ``cohort_id`` + - integer + - The numeric ID of the cohort group. + * - ``cohort_name`` + - string + - The display name of the cohort group. + * - ``previous_cohort_id`` + - integer + - The numeric ID of the cohort group that the user was previously assigned + to (or null if the user was not previously assigned to a cohort group). + * - ``previous_cohort_name`` + - string + - The display name of the cohort group that the user was previously + assigned to (or null if the user was not previously assigned to a cohort + group). + .. _Creating a Peer Assessment: http://edx.readthedocs.org/projects/edx-open-response-assessments/en/latest/