Skip to content

E
edx-platform
Commit 98bf627e by sandroroux
Options

Revised content above "Configuration flags".

parent d3cc7e9b
Showing with 107 additions and 100 deletions
openedx/core/djangoapps/schedules/README.rst
......@@ -3,145 +3,148 @@ 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 a course. Learners receive these messages at important milestones
in their learning.
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 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":
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
Recurring Nudges encourage learners to return to 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.
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.
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 sends a weekly email with these
highlights listed in 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".
The app introduces a Schedule object to the edX codebase. Learners receive
Schedules when they enroll in self-paced courses. The app uses Schedules to
determine which learners to message.
Glossary
--------
- **Schedule**: Stores the day a learner enrolls in a course and the
learner's "upgrade deadline".
- **Schedule**: Stores the day a learner enrolls in a course and the learner’s
“upgrade deadline”. Used by the app at runtime to determine which learners to
message.
- **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:
- **Schedule Experience**: Defines the set of emails that a learner
receives. The two Schedule Experiences are:
- "Recurring Nudge and Upgrade Reminder"
- "Course Updates"
- “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
verified certificate. By default, a Schedule imposes a “soft” upgrade
deadline 21 days from when a learner enrolled in a course. A course
also imposes a “hard” upgrade deadline. A Schedule uses whichever
date is earlier.
- **Course Update**: We refer to “Weekly Course Highlight Messages” as “Course
Updates” in the code. In contexts outside of this app, Course Updates refer to
bulk-emails sent by course instructors. We plan on removing this term from the
code to avoid confusion.
- **Section**: From our
`documentation <http://edx.readthedocs.io/projects/edx-%20partner-course-staff/en/latest/developing_course/course_sections.html#what-is-a-section>`__,
“A section is the topmost category in your course. A section can
represent a time period in your course, a chapter, or another
organizing principle. A section contains one or more subsections.”
For the purposes of Weekly Section Highlights Messages, we assume
that a section contains a week’s worth of learning material.
- **Weekly Section Highlights**: A list of topics that learners will
encounter in a section of a course. Course authors enter section
highlights in the Studio UI.
- **Resolver**: A Python class that identifies which learners to
message and sends them emails. We create a Resolver subclass to
manage each message type. An “UpgradeReminderResolver” sends Upgrade
Reminder messages, a “RecurringNudgeResolver” sends Recurring Nudge
messages, and a “CourseUpdateResolver” sends Weekly Section Highlight
Messages.
- **MessageType**: A Python class that represents a kind of email
message. It specifies the Django template the app uses the render the
email. `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.
the main Django LMS process. In the app, a task is created to email
groups of learners. We bin learners to distribute the amount of work
each task performs. We email each bin's worth of learners in a task.
- **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.
- **Bin**: In the Schedules app, we divide the learners we are emailing
into N “bins” (by default, N is 24). We do this to evenly distribute
the number of emails each task must send.
- **Email Backend**
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``.
There are three management commands in the Schedules app. Each command sends a
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.:
You must specify the Site for which you are sending emails in the command:
::
./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:
Make sure to specify your development environment with the “settings”
flag. For example, if you are running a command in docker devstack, you
can use:
::
./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.
You can override the “current date” when running a command. The app will run,
using the date you specify as its "today":
::
./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.
If the app is paired with Sailthru, you can override which email addresses the
app sends to. The app will send all emails to the address you specify:
::
./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.
These management commands are meant to be run daily. We schedule them to
run automatically in a Jenkins job. You can use a similar automation
tool, like “cron”, to schedule a daily run of the app.
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
are 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.
for information on setting 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.
The Schedule app relies on ACE. When live, ACE sends emails to users
through Sailthru. You can instead configure ACE to write emails
to the local filesystem, which can be useful for debugging.
File Back-end
~~~~~~~~~~~~~
......@@ -153,23 +156,23 @@ add/change the following:
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.
By default, your devstack should be configured to use the ``file_email``
ACE channel. This ACE channel saves the emails to
``/path/to/your/devstack/src/ace_messages/*.html`` on your host machine
(the host path corresponds to ``/edx/src/ace_messages/`` in your devstack docker
container). To view the emails, open the saved files in your browser.
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
To configure ACE to 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``:
Make sure to add the following settings in either ``lms/envs/common.py``
or ``lms/envs/private.py``:
.. code:: python
......@@ -181,8 +184,8 @@ Additionally, make sure these are set in either the
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.
These settings populate links in the emails to external
social media, marketing websites, app stores, etc.
Edit the ``lms/envs/common.py`` or ``lms/envs/private.py`` and
add/change the following:
......@@ -246,7 +249,7 @@ 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
``<studio_url>/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
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.
......@@ -276,8 +279,8 @@ 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
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
......@@ -291,6 +294,8 @@ linked with the course with the "Mode" equal to "verified".
Configuring Email Sending
~~~~~~~~~~~~~~~~~~~~~~~~~
.. scheduleconfig-1:
ScheduleConfig
^^^^^^^^^^^^^^
......@@ -303,6 +308,8 @@ configure enqueueing and delivering emails per message type:
- ``deliver_*``: allows delivering emails through ACE for this message
type.
.. roll-out-waffle-flag-1:
Roll-out Waffle Flag
^^^^^^^^^^^^^^^^^^^^
......@@ -320,7 +327,7 @@ authors to enter section highlights can be toggled globally by going to
This is a roll-out related waffle switch that we will eventually delete.
Configuring a Learner's Schedule
Configuring a Learner’s Schedule
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Emails will only be sent to learners who have Schedule ``start_date``\ s
......@@ -338,15 +345,15 @@ Recurring Nudge
Upgrade Reminder
^^^^^^^^^^^^^^^^
- Learners must have the ScheduleExperience type of "Recurring Nudge
and 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".
- 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.
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment