diff --git a/openedx/core/djangoapps/schedules/README.md b/openedx/core/djangoapps/schedules/README.md deleted file mode 100644 index a5a5edfc1f..0000000000 --- a/openedx/core/djangoapps/schedules/README.md +++ /dev/null @@ -1,327 +0,0 @@ -# Dynamic Pacing Schedules - -The Schedules app allows course teams to automatically email learners in -self-paced courses. The emails are designed to keep learners engaged with a -course's content. Learners receive these messages at important milestones -throughout a course. - -With Schedules, the author of a self-paced course opts learners into one of -two "Schedule Experiences". Learners either receive Weekly Course Highlight -Messages, or a combination of Recurring Nudges and Upgrade Reminders. - -The app can send all three message types "out of the box": - - - Recurring Nudges - - Upgrade Reminders - - Weekly Course Highlight Messages - -Recurring Nudges encourage learners to engage with self-paced courses at regular -intervals. The app sends nudges three days and ten days after a learner -enrolls in a course. - -Upgrade Reminders ask learners to purchase their course's "Verified" -certificate. The reminders are sent two days from their course's upgrade -deadline, or two days from the course's end date. Whichever date occurs sooner. - -Weekly Course Highlight Messages tell learners what to look forward to in the -coming week of a course. Course authors provide "section highlights" when -authoring a course in Studio. The app generates emails with these section -highlights listed in the body of the message. - -The app introduces the Schedule object to the edX codebase. Learners receive -Schedules when they enroll in self-paced courses. With Schedules, the app -determines when to send particular messages. It assumes a steady rate of -progress through course materials. It determines the cadence of its messaging -through a course's "Schedule Experience". - - -## Glossary - -* **Schedule**: Stores the day a learner enrolls in a course and the learner's - "upgrade deadline". - -* **Schedule Experience**: Defines which set of emails that a learner will - receive so that they have a consistent email experience throughout their time - in the course even if a course author makes changes to the course after they - enroll. Right now, the possible Schedule Experiences are: - * "Recurring Nudge and Upgrade Reminder" - * "Course Updates" - -* **Upgrade Deadline**: The date before which a learner can purchase a verified - certificate. A Schedule imposes a "soft" upgrade deadline 21 days from when a - learner enrolled in a course. A self-paced course imposes a "hard" upgrade - deadline that is the course-wide expiration date for upgrading on the course. - A learner's Schedule will use whichever date is earlier. - -* **Course Update**: In the code, we refer to Weekly Course Highlight messages - as Course Updates. In hindsight, this is confusing since we also use the term - Course Updates to refer to bulk-emails manually sent out by course - instructors. We haven't had the chance to rename these variables in the code - yet. - -* **Highlights**: A list of topics that learners should expect to learn in a - section of a course. These are defined by course authors in the Studio UI. - -* **Resolver**: Python class that defines which learners to filter to for the - message type and then creates and sends an email to each of those learners. - -* **MessageType**: Python class that defines a particular kind of email message - and the Django template it uses. [MessageType is an ACE - concept](https://edx-ace.readthedocs.io/en/latest/modules.html#edx_ace.message.MessageType). - -* **Task**: A [Celery](http://docs.celeryproject.org/en/latest/index.html) - asynchronous class/function that is run in a separate process from the main - Django LMS process. We have to serialize all data we send to a task to a - string. In the Schedules app, a task is created for every bin of learners. - -* **Bin**: In the Schedules app, we divide the learners that we want to send - emails to into N "bins" (default is 24). This is so that each Celery task only - has to process approximately 1,000 emails each. - - -## Running the Management Commands - -To initiate the celery tasks that query for users and then send emails, run one -of the management commands in the Schedules app. There is one command per -message type: `send_recurring_nudge`, `send_upgrade_reminder`, and -`send_course_update`. - -The command requires you to specify for which Site to send emails. E.g.: - -``` -./manage.py lms send_recurring_nudge example.com -``` - -Make sure to specify the settings for the environment you are running the -management command in. For example, in docker devstack this would be: - -``` -./manage.py lms --settings devstack_docker send_recurring_nudge example.com -``` - -You have the option to override the current date in order to run the command as -if it were run on that day. - -``` -./manage.py lms --settings devstack_docker send_recurring_nudge example.com --date 2017-11-13 -``` - -If you have Sailthru configured in the current environment, you also have the -option to override the recipient email addresses so that all of the emails are -sent to the address that you specify instead of to the users' emails. - -``` -./manage.py lms --settings devstack_docker send_recurring_nudge example.com --override-recipient-email developer@example.com -``` - -These management commands are intended to be run on a daily basis, so it is -recommended to execute them in a Cron job or Jenkins job scheduled to run -automatically every day. - - -## Configuring A.C.E. - -These instructions assume you have already setup an Open edX instance or have a -Running devstack. See the [Open edX Developer's -Guide](http://edx.readthedocs.io/projects/edx-developer-guide/en/latest/) for -information on how to set them up. - -The Schedule app relies on ACE. ACE can be configured to send emails to a file -or send emails through Sailthru which actually delivers emails to users. - -### File Back-end - -Edit the `lms/envs/common.py` or `lms/envs/private.py`and add/change the -following: - -```python -ACE_CHANNEL_SAILTHRU_DEBUG = True -``` - -By default your devstack should be configured to use the `file_email` ACE -channel which saves the HTML emails to -`/path/to/your/devstack/src/ace_messages/*.html` on your host (or -`/edx/src/ace_messages/` in your devstack docker container). Open the files in -your browser to view the emails. - -### Sailthru Back-end - -To configure ACE to actually send emails to users' email addresses, add a -[Sailthru](http://www.sailthru.com/) back-end configuration. See the [edx-ace -documentation](https://edx-ace.readthedocs.io/en/latest/getting_started.html#sailthruemailchannel-settings) -for instructions on setting up a Sailthru API key and secret. - -Additionally, make sure these are set in either the `lms/envs/common.py` or -`lms/envs/private.py`: - -```python -ACE_CHANNEL_SAILTHRU_DEBUG = False -ACE_ENABLED_CHANNEL = ['sailthru_email'] -ACE_ENABLED_POLICIES = ['bulk_email_optout'] -ACE_CHANNEL_SAILTHRU_TEMPLATE_NAME = '' -``` - - -## Django Settings - -Regardless of which ACE back-end you use, make sure to set the following Django -settings so that all of the features of the emails are enabled. - -Edit the `lms/envs/common.py` or `lms/envs/private.py` and add/change the -following: - -```python -FEATURES = { - 'ENABLE_MKTG_SITE': True, -} -MKTG_URLS = { - 'ROOT': '', -} -SOCIAL_MEDIA_FOOTER_URLS = { - 'tumblr': '', - 'reddit': '', - 'twitter': '', - 'google_plus': '', - 'youtube': '', - 'linkedin': '', - 'meetup': '', - 'facebook': '', -} -MOBILE_STORE_URLS = { - 'google': '', - 'apple': '', -} -CONTACT_MAILING_ADDRESS = '' -``` - - -## Configuration Flags - -### Configuring Schedule Creation - -Make sure a Site has been created at `/admin/sites/site`. - -#### ScheduleConfig - -In the Django admin panel at `/admin/schedules/scheduleconfig/` create -a ScheduleConfig and link it to the Site. Make sure to enable all of the -settings: - -* `create_schedules`: enables creating new Schedules when new Course Enrollments - are created. -* `hold_back_ratio`: ratio of all new Course Enrollments that should NOT have a - Schedule created. - -#### Roll-out Waffle Flag - -There is one roll-out related course waffle flag that we plan to delete called -`schedules.create_schedules_for_course`, which, if the -`ScheduleConfig.create_schedules` is disabled, will enable schedule creation on -a per-course basis. - -#### Self-paced Configuration - -Schedules will only be created for a course if it is self-paced. A course can be -configured to be self-paced by going to -`/admin/self_paced/selfpacedconfiguration/` and adding an enabled -self paced config. Then, go to Studio settings for the course and change the -Course Pacing value to "Self-Paced". Note that the Course Start Date has to be -set to sometime in the future in order to change the Course Pacing. - - -### Configuring Upgrade Deadline on Schedule - -The upgrade reminder message type depends on there being a date in the -`upgrade_deadline` field of the Schedule model. Up-sell messaging will also be -added to the recurring nudge and course updates message types when an upgrade -deadline date is present. - -#### DynamicUpgradeDeadlineConfiguration models - -In order to enable filling in the `upgrade_deadline` field of new Schedule -models created, you must create and enable one of the following: - -* A DynamicUpgradeDeadlineConfiguration toggles the feature for all courses - globally. -* A OrgDynamicUpgradeDeadlineConfiguration toggles the feature for all courses - in a particular organization. -* A CourseDynamicUpgradeDeadlineConfiguration toggles the feature for a - particular course. - -The CourseDynamicUpgradeDeadlineConfiguration takes precedence over the -OrgDynamicUpgradeDeadlineConfiguration which takes precedence over the global -DynamicUpgradeDeadlineConfiguration. - -The "deadline days" field specifies how many days from the day of the learner's -enrollment will be their soft upgrade deadline on the Schedule model. - -#### Verified Course Mode - -The `upgrade_deadline` will only be filled for a course if it has a verified -course mode. To add a verified course mode to a course, go to -`/admin/course_modes/coursemode/` and add a course mode linked with -the course with the "Mode" equal to "verified". - -### Configuring Email Sending - -#### ScheduleConfig - -The ScheduleConfig model at `/admin/schedules/scheduleconfig/` also has -fields which configure enqueueing and delivering emails per message type: - -* `enqueue_*`: allows sending email tasks of this message type to celery. -* `deliver_*`: allows delivering emails through ACE for this message type. - -#### Roll-out Waffle Flag - -Another roll-out related course waffle flag that we plan to delete called -`schedules.send_updates_for_course` will enable sending specifically the course -updates email per-course. - - -### Configuring Highlights UI in Studio - -The button and modal on the course outline page that allows course authors to -enter section highlights can be toggled globally by going to -`/admin/waffle/switch/` and adding an active switch called -`dynamic_pacing.studio_course_update`. - -This is a roll-out related waffle switch that we will eventually delete. - - -### Configuring a Learner's Schedule - -Emails will only be sent to learners who have Schedule `start_date`s or -`upgrade_deadline`s and ScheduleExperience that match the criteria for the -message type. - -#### Recurring Nudge - -* Learners must have the ScheduleExperience type of "Recurring Nudge and Upgrade -Reminder". -* Their Schedule `start_date` must be 3 or 10 days before the current date. - -#### Upgrade Reminder - -* Learners must have the ScheduleExperience type of "Recurring Nudge and Upgrade -Reminder". -* Their Schedule `upgrade_deadline` must be 2 days after the current date. - -#### Course Update - -* Learners must have the ScheduleExperience type of "Course Updates". -* Their Schedule `start_date` must be 7, 14, or any increment of 7 days up to 77 - days before the current date. - - -## Litmus - -When designing email templates, it is important to test the rendered emails in a -variety of email clients to ensure there are no bugs in any of them. EdX uses a -tool called [Litmus](http://litmus.com/) that automates this process. - -To begin using Litmus, make sure that ACE is configured to use Sailthru, and -then refer to the confluence page on [How to test emails in a variety of -clients](https://openedx.atlassian.net/wiki/spaces/RET/pages/216563991/How+to+test+emails+in+a+variety+of+clients) -which will explain how to send emails to Litmus using the -`--override-recipient-email` option to the management commands. diff --git a/openedx/core/djangoapps/schedules/README.rst b/openedx/core/djangoapps/schedules/README.rst new file mode 100644 index 0000000000..52ba627974 --- /dev/null +++ b/openedx/core/djangoapps/schedules/README.rst @@ -0,0 +1,366 @@ +Dynamic Pacing Schedules +======================== + +The Schedules app allows course teams to automatically email learners in +self-paced courses. The emails are designed to keep learners engaged +with a course's content. Learners receive these messages at important +milestones throughout a course. + +With Schedules, the author of a self-paced course opts learners into one +of two "Schedule Experiences". Learners either receive Weekly Course +Highlight Messages, or a combination of Recurring Nudges and Upgrade +Reminders. + +The app can send all three message types "out of the box": + +- Recurring Nudges +- Upgrade Reminders +- Weekly Course Highlight Messages + +Recurring Nudges encourage learners to engage with self-paced courses at +regular intervals. The app sends nudges three days and ten days after a +learner enrolls in a course. + +Upgrade Reminders ask learners to purchase their course's "Verified" +certificate. The reminders are sent two days from their course's upgrade +deadline, or two days from the course's end date. Whichever date occurs +sooner. + +Weekly Course Highlight Messages tell learners what to look forward to +in the coming week of a course. Course authors provide "section +highlights" when authoring a course in Studio. The app generates emails +with these section highlights listed in the body of the message. + +The app introduces the Schedule object to the edX codebase. Learners +receive Schedules when they enroll in self-paced courses. With +Schedules, the app determines when to send particular messages. It +assumes a steady rate of progress through course materials. It +determines the cadence of its messaging through a course's "Schedule +Experience". + +Glossary +-------- + +- **Schedule**: Stores the day a learner enrolls in a course and the + learner's "upgrade deadline". + +- **Schedule Experience**: Defines which set of emails that a learner + will receive so that they have a consistent email experience + throughout their time in the course even if a course author makes + changes to the course after they enroll. Right now, the possible + Schedule Experiences are: + + - "Recurring Nudge and Upgrade Reminder" + - "Course Updates" + +- **Upgrade Deadline**: The date before which a learner can purchase a + verified certificate. A Schedule imposes a "soft" upgrade deadline 21 + days from when a learner enrolled in a course. A self-paced course + imposes a "hard" upgrade deadline that is the course-wide expiration + date for upgrading on the course. A learner's Schedule will use + whichever date is earlier. + +- **Course Update**: In the code, we refer to Weekly Course Highlight + messages as Course Updates. In hindsight, this is confusing since we + also use the term Course Updates to refer to bulk-emails manually + sent out by course instructors. We haven't had the chance to rename + these variables in the code yet. + +- **Highlights**: A list of topics that learners should expect to learn + in a section of a course. These are defined by course authors in the + Studio UI. + +- **Resolver**: Python class that defines which learners to filter to + for the message type and then creates and sends an email to each of + those learners. + +- **MessageType**: Python class that defines a particular kind of email + message and the Django template it uses. `MessageType is an ACE + concept `__. + +- **Task**: A + `Celery `__ + asynchronous class/function that is run in a separate process from + the main Django LMS process. We have to serialize all data we send to + a task to a string. In the Schedules app, a task is created for every + bin of learners. + +- **Bin**: In the Schedules app, we divide the learners that we want to + send emails to into N "bins" (default is 24). This is so that each + Celery task only has to process approximately 1,000 emails each. + +Running the Management Commands +------------------------------- + +To initiate the celery tasks that query for users and then send emails, +run one of the management commands in the Schedules app. There is one +command per message type: ``send_recurring_nudge``, +``send_upgrade_reminder``, and ``send_course_update``. + +The command requires you to specify for which Site to send emails. E.g.: + +:: + + ./manage.py lms send_recurring_nudge example.com + +Make sure to specify the settings for the environment you are running +the management command in. For example, in docker devstack this would +be: + +:: + + ./manage.py lms --settings devstack_docker send_recurring_nudge example.com + +You have the option to override the current date in order to run the +command as if it were run on that day. + +:: + + ./manage.py lms --settings devstack_docker send_recurring_nudge example.com --date 2017-11-13 + +If you have Sailthru configured in the current environment, you also +have the option to override the recipient email addresses so that all of +the emails are sent to the address that you specify instead of to the +users' emails. + +:: + + ./manage.py lms --settings devstack_docker send_recurring_nudge example.com --override-recipient-email developer@example.com + +These management commands are intended to be run on a daily basis, so it +is recommended to execute them in a Cron job or Jenkins job scheduled to +run automatically every day. + +Configuring A.C.E. +------------------ + +These instructions assume you have already setup an Open edX instance or +have a Running devstack. See the `Open edX Developer's +Guide `__ +for information on how to set them up. + +The Schedule app relies on ACE. ACE can be configured to send emails to +a file or send emails through Sailthru which actually delivers emails to +users. + +File Back-end +~~~~~~~~~~~~~ + +Edit the ``lms/envs/common.py`` or ``lms/envs/private.py``\ and +add/change the following: + +.. code:: python + + ACE_CHANNEL_SAILTHRU_DEBUG = True + +By default your devstack should be configured to use the ``file_email`` +ACE channel which saves the HTML emails to +``/path/to/your/devstack/src/ace_messages/*.html`` on your host (or +``/edx/src/ace_messages/`` in your devstack docker container). Open the +files in your browser to view the emails. + +Sailthru Back-end +~~~~~~~~~~~~~~~~~ + +To configure ACE to actually send emails to users' email addresses, add +a `Sailthru `__ back-end configuration. See +the `edx-ace +documentation `__ +for instructions on setting up a Sailthru API key and secret. + +Additionally, make sure these are set in either the +``lms/envs/common.py`` or ``lms/envs/private.py``: + +.. code:: python + + ACE_CHANNEL_SAILTHRU_DEBUG = False + ACE_ENABLED_CHANNEL = ['sailthru_email'] + ACE_ENABLED_POLICIES = ['bulk_email_optout'] + ACE_CHANNEL_SAILTHRU_TEMPLATE_NAME = '' + +Django Settings +--------------- + +Regardless of which ACE back-end you use, make sure to set the following +Django settings so that all of the features of the emails are enabled. + +Edit the ``lms/envs/common.py`` or ``lms/envs/private.py`` and +add/change the following: + +.. code:: python + + FEATURES = { + 'ENABLE_MKTG_SITE': True, + } + MKTG_URLS = { + 'ROOT': '', + } + SOCIAL_MEDIA_FOOTER_URLS = { + 'tumblr': '', + 'reddit': '', + 'twitter': '', + 'google_plus': '', + 'youtube': '', + 'linkedin': '', + 'meetup': '', + 'facebook': '', + } + MOBILE_STORE_URLS = { + 'google': '', + 'apple': '', + } + CONTACT_MAILING_ADDRESS = '' + +Configuration Flags +------------------- + +Configuring Schedule Creation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Make sure a Site has been created at ``/admin/sites/site``. + +ScheduleConfig +^^^^^^^^^^^^^^ + +In the Django admin panel at +``/admin/schedules/scheduleconfig/`` create a ScheduleConfig +and link it to the Site. Make sure to enable all of the settings: + +- ``create_schedules``: enables creating new Schedules when new Course + Enrollments are created. +- ``hold_back_ratio``: ratio of all new Course Enrollments that should + NOT have a Schedule created. + +Roll-out Waffle Flag +^^^^^^^^^^^^^^^^^^^^ + +There is one roll-out related course waffle flag that we plan to delete +called ``schedules.create_schedules_for_course``, which, if the +``ScheduleConfig.create_schedules`` is disabled, will enable schedule +creation on a per-course basis. + +Self-paced Configuration +^^^^^^^^^^^^^^^^^^^^^^^^ + +Schedules will only be created for a course if it is self-paced. A +course can be configured to be self-paced by going to +``/admin/self_paced/selfpacedconfiguration/`` and adding an +enabled self paced config. Then, go to Studio settings for the course +and change the Course Pacing value to "Self-Paced". Note that the Course +Start Date has to be set to sometime in the future in order to change +the Course Pacing. + +Configuring Upgrade Deadline on Schedule +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The upgrade reminder message type depends on there being a date in the +``upgrade_deadline`` field of the Schedule model. Up-sell messaging will +also be added to the recurring nudge and course updates message types +when an upgrade deadline date is present. + +DynamicUpgradeDeadlineConfiguration models +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In order to enable filling in the ``upgrade_deadline`` field of new +Schedule models created, you must create and enable one of the +following: + +- A DynamicUpgradeDeadlineConfiguration toggles the feature for all + courses globally. +- A OrgDynamicUpgradeDeadlineConfiguration toggles the feature for all + courses in a particular organization. +- A CourseDynamicUpgradeDeadlineConfiguration toggles the feature for a + particular course. + +The CourseDynamicUpgradeDeadlineConfiguration takes precedence over the +OrgDynamicUpgradeDeadlineConfiguration which takes precedence over the +global DynamicUpgradeDeadlineConfiguration. + +The "deadline days" field specifies how many days from the day of the +learner's enrollment will be their soft upgrade deadline on the Schedule +model. + +Verified Course Mode +^^^^^^^^^^^^^^^^^^^^ + +The ``upgrade_deadline`` will only be filled for a course if it has a +verified course mode. To add a verified course mode to a course, go to +``/admin/course_modes/coursemode/`` and add a course mode +linked with the course with the "Mode" equal to "verified". + +Configuring Email Sending +~~~~~~~~~~~~~~~~~~~~~~~~~ + +ScheduleConfig +^^^^^^^^^^^^^^ + +The ScheduleConfig model at +``/admin/schedules/scheduleconfig/`` also has fields which +configure enqueueing and delivering emails per message type: + +- ``enqueue_*``: allows sending email tasks of this message type to + celery. +- ``deliver_*``: allows delivering emails through ACE for this message + type. + +Roll-out Waffle Flag +^^^^^^^^^^^^^^^^^^^^ + +Another roll-out related course waffle flag that we plan to delete +called ``schedules.send_updates_for_course`` will enable sending +specifically the course updates email per-course. + +Configuring Highlights UI in Studio +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The button and modal on the course outline page that allows course +authors to enter section highlights can be toggled globally by going to +``/admin/waffle/switch/`` and adding an active switch called +``dynamic_pacing.studio_course_update``. + +This is a roll-out related waffle switch that we will eventually delete. + +Configuring a Learner's Schedule +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Emails will only be sent to learners who have Schedule ``start_date``\ s +or ``upgrade_deadline``\ s and ScheduleExperience that match the +criteria for the message type. + +Recurring Nudge +^^^^^^^^^^^^^^^ + +- Learners must have the ScheduleExperience type of "Recurring Nudge + and Upgrade Reminder". +- Their Schedule ``start_date`` must be 3 or 10 days before the current + date. + +Upgrade Reminder +^^^^^^^^^^^^^^^^ + +- Learners must have the ScheduleExperience type of "Recurring Nudge + and Upgrade Reminder". +- Their Schedule ``upgrade_deadline`` must be 2 days after the current + date. + +Course Update +^^^^^^^^^^^^^ + +- Learners must have the ScheduleExperience type of "Course Updates". +- Their Schedule ``start_date`` must be 7, 14, or any increment of 7 + days up to 77 days before the current date. + +Litmus +------ + +When designing email templates, it is important to test the rendered +emails in a variety of email clients to ensure there are no bugs in any +of them. EdX uses a tool called `Litmus `__ that +automates this process. + +To begin using Litmus, make sure that ACE is configured to use Sailthru, +and then refer to the confluence page on `How to test emails in a +variety of +clients `__ +which will explain how to send emails to Litmus using the +``--override-recipient-email`` option to the management commands.