enrollment.py 16.7 KB
Newer Older
1 2 3 4 5 6
"""
Enrollment operations for use by instructor APIs.

Does not include any access control, be sure to check access before calling.
"""

7
import json
8
import logging
9
from django.contrib.auth.models import User
10 11 12
from django.conf import settings
from django.core.urlresolvers import reverse
from django.core.mail import send_mail
13
from django.utils.translation import override as override_language
14

15
from course_modes.models import CourseMode
16
from student.models import CourseEnrollment, CourseEnrollmentAllowed
17
from courseware.models import StudentModule
David Baumgold committed
18
from edxmako.shortcuts import render_to_string
19
from lang_pref import LANGUAGE_KEY
20

21
from submissions import api as sub_api  # installed from the edx-submissions repository
22
from student.models import anonymous_id_for_user
23
from openedx.core.djangoapps.user_api.models import UserPreference
24

25
from microsite_configuration import microsite
26 27 28 29 30
from xmodule.modulestore.django import modulestore
from xmodule.modulestore.exceptions import ItemNotFoundError


log = logging.getLogger(__name__)
31

32

33 34 35 36
class EmailEnrollmentState(object):
    """ Store the complete enrollment state of an email in a class """
    def __init__(self, course_id, email):
        exists_user = User.objects.filter(email=email).exists()
37 38
        if exists_user:
            user = User.objects.get(email=email)
39 40 41
            mode, is_active = CourseEnrollment.enrollment_mode_for_user(user, course_id)
            # is_active is `None` if the user is not enrolled in the course
            exists_ce = is_active is not None and is_active
42
            full_name = user.profile.name
43
        else:
44
            mode = None
45
            exists_ce = False
46
            full_name = None
47
        ceas = CourseEnrollmentAllowed.objects.filter(course_id=course_id, email=email).all()
48
        exists_allowed = ceas.exists()
49 50 51 52 53 54
        state_auto_enroll = exists_allowed and ceas[0].auto_enroll

        self.user = exists_user
        self.enrollment = exists_ce
        self.allowed = exists_allowed
        self.auto_enroll = bool(state_auto_enroll)
55
        self.full_name = full_name
56
        self.mode = mode
57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83

    def __repr__(self):
        return "{}(user={}, enrollment={}, allowed={}, auto_enroll={})".format(
            self.__class__.__name__,
            self.user,
            self.enrollment,
            self.allowed,
            self.auto_enroll,
        )

    def to_dict(self):
        """
        example: {
            'user': False,
            'enrollment': False,
            'allowed': True,
            'auto_enroll': True,
        }
        """
        return {
            'user': self.user,
            'enrollment': self.enrollment,
            'allowed': self.allowed,
            'auto_enroll': self.auto_enroll,
        }


84 85 86 87 88
def get_user_email_language(user):
    """
    Return the language most appropriate for writing emails to user. Returns
    None if the preference has not been set, or if the user does not exist.
    """
89 90 91
    # Calling UserPreference directly instead of get_user_preference because the user requesting the
    # information is not "user" and also may not have is_staff access.
    return UserPreference.get_value(user, LANGUAGE_KEY)
92 93 94


def enroll_email(course_id, student_email, auto_enroll=False, email_students=False, email_params=None, language=None):
95
    """
96
    Enroll a student by email.
97

98 99 100 101
    `student_email` is student's emails e.g. "foo@bar.com"
    `auto_enroll` determines what is put in CourseEnrollmentAllowed.auto_enroll
        if auto_enroll is set, then when the email registers, they will be
        enrolled in the course automatically.
102 103
    `email_students` determines if student should be notified of action by email.
    `email_params` parameters used while parsing email templates (a `dict`).
104
    `language` is the language used to render the email.
105

106 107
    returns two EmailEnrollmentState's
        representing state before and after the action.
108
    """
109
    previous_state = EmailEnrollmentState(course_id, student_email)
110
    enrollment_obj = None
111
    if previous_state.user:
112 113
        # if the student is currently unenrolled, don't enroll them in their
        # previous mode
114 115 116 117 118 119 120 121

        # for now, White Labels use 'shoppingcart' which is based on the
        # "honor" course_mode. Given the change to use "audit" as the default
        # course_mode in Open edX, we need to be backwards compatible with
        # how White Labels approach enrollment modes.
        if CourseMode.is_white_label(course_id):
            course_mode = CourseMode.DEFAULT_SHOPPINGCART_MODE_SLUG
        else:
122
            course_mode = None
123

124 125 126
        if previous_state.enrollment:
            course_mode = previous_state.mode

127
        enrollment_obj = CourseEnrollment.enroll_by_email(student_email, course_id, course_mode)
128 129 130 131
        if email_students:
            email_params['message'] = 'enrolled_enroll'
            email_params['email_address'] = student_email
            email_params['full_name'] = previous_state.full_name
132
            send_mail_to_student(student_email, email_params, language=language)
133 134 135 136
    else:
        cea, _ = CourseEnrollmentAllowed.objects.get_or_create(course_id=course_id, email=student_email)
        cea.auto_enroll = auto_enroll
        cea.save()
137 138 139
        if email_students:
            email_params['message'] = 'allowed_enroll'
            email_params['email_address'] = student_email
140
            send_mail_to_student(student_email, email_params, language=language)
141

142 143
    after_state = EmailEnrollmentState(course_id, student_email)

144
    return previous_state, after_state, enrollment_obj
145 146


147
def unenroll_email(course_id, student_email, email_students=False, email_params=None, language=None):
148
    """
149
    Unenroll a student by email.
150

151
    `student_email` is student's emails e.g. "foo@bar.com"
152 153
    `email_students` determines if student should be notified of action by email.
    `email_params` parameters used while parsing email templates (a `dict`).
154
    `language` is the language used to render the email.
155

156 157
    returns two EmailEnrollmentState's
        representing state before and after the action.
158
    """
159 160
    previous_state = EmailEnrollmentState(course_id, student_email)
    if previous_state.enrollment:
161
        CourseEnrollment.unenroll_by_email(student_email, course_id)
162 163 164 165
        if email_students:
            email_params['message'] = 'enrolled_unenroll'
            email_params['email_address'] = student_email
            email_params['full_name'] = previous_state.full_name
166
            send_mail_to_student(student_email, email_params, language=language)
167 168 169

    if previous_state.allowed:
        CourseEnrollmentAllowed.objects.get(course_id=course_id, email=student_email).delete()
170 171 172 173
        if email_students:
            email_params['message'] = 'allowed_unenroll'
            email_params['email_address'] = student_email
            # Since no User object exists for this student there is no "full_name" available.
174
            send_mail_to_student(student_email, email_params, language=language)
175 176

    after_state = EmailEnrollmentState(course_id, student_email)
177

178
    return previous_state, after_state
179 180


181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201
def send_beta_role_email(action, user, email_params):
    """
    Send an email to a user added or removed as a beta tester.

    `action` is one of 'add' or 'remove'
    `user` is the User affected
    `email_params` parameters used while parsing email templates (a `dict`).
    """
    if action == 'add':
        email_params['message'] = 'add_beta_tester'
        email_params['email_address'] = user.email
        email_params['full_name'] = user.profile.name

    elif action == 'remove':
        email_params['message'] = 'remove_beta_tester'
        email_params['email_address'] = user.email
        email_params['full_name'] = user.profile.name

    else:
        raise ValueError("Unexpected action received '{}' - expected 'add' or 'remove'".format(action))

202
    send_mail_to_student(user.email, email_params, language=get_user_email_language(user))
203 204


Miles Steele committed
205
def reset_student_attempts(course_id, student, module_state_key, delete_module=False):
206 207 208 209 210 211
    """
    Reset student attempts for a problem. Optionally deletes all student state for the specified problem.

    In the previous instructor dashboard it was possible to modify/delete
    modules that were not problems. That has been disabled for safety.

212 213 214 215
    `student` is a User
    `problem_to_reset` is the name of a problem e.g. 'L2Node1'.
    To build the module_state_key 'problem/' and course information will be appended to `problem_to_reset`.

216 217 218 219 220
    Raises:
        ValueError: `problem_state` is invalid JSON.
        StudentModule.DoesNotExist: could not load the student module.
        submissions.SubmissionError: unexpected error occurred while resetting the score in the submissions API.

221
    """
222 223 224 225 226 227 228 229 230 231 232 233 234
    try:
        # A block may have children. Clear state on children first.
        block = modulestore().get_item(module_state_key)
        if block.has_children:
            for child in block.children:
                try:
                    reset_student_attempts(course_id, student, child, delete_module=delete_module)
                except StudentModule.DoesNotExist:
                    # If a particular child doesn't have any state, no big deal, as long as the parent does.
                    pass
    except ItemNotFoundError:
        log.warning("Could not find %s in modulestore when attempting to reset attempts.", module_state_key)

235 236 237 238 239 240 241
    # Reset the student's score in the submissions API
    # Currently this is used only by open assessment (ORA 2)
    # We need to do this *before* retrieving the `StudentModule` model,
    # because it's possible for a score to exist even if no student module exists.
    if delete_module:
        sub_api.reset_score(
            anonymous_id_for_user(student, course_id),
242 243
            course_id.to_deprecated_string(),
            module_state_key.to_deprecated_string(),
244 245 246 247 248
        )

    module_to_reset = StudentModule.objects.get(
        student_id=student.id,
        course_id=course_id,
249
        module_state_key=module_state_key
250
    )
251 252 253 254 255 256 257 258

    if delete_module:
        module_to_reset.delete()
    else:
        _reset_module_attempts(module_to_reset)


def _reset_module_attempts(studentmodule):
259 260 261 262 263
    """
    Reset the number of attempts on a studentmodule.

    Throws ValueError if `problem_state` is invalid JSON.
    """
264 265 266 267 268 269 270 271
    # load the state json
    problem_state = json.loads(studentmodule.state)
    # old_number_of_attempts = problem_state["attempts"]
    problem_state["attempts"] = 0

    # save
    studentmodule.state = json.dumps(problem_state)
    studentmodule.save()
272 273


274
def get_email_params(course, auto_enroll, secure=True, course_key=None, display_name=None):
275 276 277 278 279 280 281
    """
    Generate parameters used when parsing email templates.

    `auto_enroll` is a flag for auto enrolling non-registered students: (a `boolean`)
    Returns a dict of parameters
    """

282
    protocol = 'https' if secure else 'http'
283
    course_key = course_key or course.id.to_deprecated_string()
284
    display_name = display_name or course.display_name_with_default_escaped
285

286 287 288 289
    stripped_site_name = microsite.get_value(
        'SITE_NAME',
        settings.SITE_NAME
    )
290
    # TODO: Use request.build_absolute_uri rather than '{proto}://{site}{path}'.format
291
    # and check with the Services team that this works well with microsites
292 293 294
    registration_url = u'{proto}://{site}{path}'.format(
        proto=protocol,
        site=stripped_site_name,
295
        path=reverse('register_user')
296
    )
297 298 299
    course_url = u'{proto}://{site}{path}'.format(
        proto=protocol,
        site=stripped_site_name,
300
        path=reverse('course_root', kwargs={'course_id': course_key})
301 302 303 304 305
    )

    # We can't get the url to the course's About page if the marketing site is enabled.
    course_about_url = None
    if not settings.FEATURES.get('ENABLE_MKTG_SITE', False):
306 307 308
        course_about_url = u'{proto}://{site}{path}'.format(
            proto=protocol,
            site=stripped_site_name,
309
            path=reverse('about_course', kwargs={'course_id': course_key})
310 311
        )

312 313 314 315 316 317 318
    is_shib_course = uses_shib(course)

    # Composition of email
    email_params = {
        'site_name': stripped_site_name,
        'registration_url': registration_url,
        'course': course,
319
        'display_name': display_name,
320
        'auto_enroll': auto_enroll,
321 322
        'course_url': course_url,
        'course_about_url': course_about_url,
323 324 325 326 327
        'is_shib_course': is_shib_course,
    }
    return email_params


328
def send_mail_to_student(student, param_dict, language=None):
329 330 331 332 333 334 335 336
    """
    Construct the email using templates and then send it.
    `student` is the student's email address (a `str`),

    `param_dict` is a `dict` with keys
    [
        `site_name`: name given to edX instance (a `str`)
        `registration_url`: url for registration (a `str`)
337
        `display_name` : display name of a course (a `str`)
338 339 340 341 342 343 344 345 346
        `course_id`: id of course (a `str`)
        `auto_enroll`: user input option (a `str`)
        `course_url`: url of course (a `str`)
        `email_address`: email of student (a `str`)
        `full_name`: student full name (a `str`)
        `message`: type of email to send and template to use (a `str`)
        `is_shib_course`: (a `boolean`)
    ]

347 348 349 350
    `language` is the language used to render the email. If None the language
    of the currently-logged in user (that is, the user sending the email) will
    be used.

351 352 353
    Returns a boolean indicating whether the email was sent successfully.
    """

354
    # add some helpers and microconfig subsitutions
355 356
    if 'display_name' in param_dict:
        param_dict['course_name'] = param_dict['display_name']
357

358
    param_dict['site_name'] = microsite.get_value(
359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385
        'SITE_NAME',
        param_dict['site_name']
    )

    subject = None
    message = None

    # see if we are running in a microsite and that there is an
    # activation email template definition available as configuration, if so, then render that
    message_type = param_dict['message']

    email_template_dict = {
        'allowed_enroll': (
            'emails/enroll_email_allowedsubject.txt',
            'emails/enroll_email_allowedmessage.txt'
        ),
        'enrolled_enroll': (
            'emails/enroll_email_enrolledsubject.txt',
            'emails/enroll_email_enrolledmessage.txt'
        ),
        'allowed_unenroll': (
            'emails/unenroll_email_subject.txt',
            'emails/unenroll_email_allowedmessage.txt'
        ),
        'enrolled_unenroll': (
            'emails/unenroll_email_subject.txt',
            'emails/unenroll_email_enrolledmessage.txt'
386 387 388 389 390 391 392 393 394
        ),
        'add_beta_tester': (
            'emails/add_beta_tester_email_subject.txt',
            'emails/add_beta_tester_email_message.txt'
        ),
        'remove_beta_tester': (
            'emails/remove_beta_tester_email_subject.txt',
            'emails/remove_beta_tester_email_message.txt'
        ),
asadiqbal08 committed
395 396 397 398
        'account_creation_and_enrollment': (
            'emails/enroll_email_enrolledsubject.txt',
            'emails/account_creation_and_enroll_emailMessage.txt'
        ),
399
    }
400

401
    subject_template, message_template = email_template_dict.get(message_type, (None, None))
402
    if subject_template is not None and message_template is not None:
403 404 405
        subject, message = render_message_to_string(
            subject_template, message_template, param_dict, language=language
        )
406

407
    if subject and message:
408 409 410 411 412
        # Remove leading and trailing whitespace from body
        message = message.strip()

        # Email subject *must not* contain newlines
        subject = ''.join(subject.splitlines())
413
        from_address = microsite.get_value(
414 415 416 417 418
            'email_from_address',
            settings.DEFAULT_FROM_EMAIL
        )

        send_mail(subject, message, from_address, [student], fail_silently=False)
419 420


421 422 423 424 425 426 427 428 429
def render_message_to_string(subject_template, message_template, param_dict, language=None):
    """
    Render a mail subject and message templates using the parameters from
    param_dict and the given language. If language is None, the platform
    default language is used.

    Returns two strings that correspond to the rendered, translated email
    subject and message.
    """
430
    language = language or settings.LANGUAGE_CODE
431 432 433 434 435 436 437 438 439 440 441 442 443
    with override_language(language):
        return get_subject_and_message(subject_template, message_template, param_dict)


def get_subject_and_message(subject_template, message_template, param_dict):
    """
    Return the rendered subject and message with the appropriate parameters.
    """
    subject = render_to_string(subject_template, param_dict)
    message = render_to_string(message_template, param_dict)
    return subject, message


444 445 446 447 448 449
def uses_shib(course):
    """
    Used to return whether course has Shibboleth as the enrollment domain

    Returns a boolean indicating if Shibboleth authentication is set for this course.
    """
450
    return course.enrollment_domain and course.enrollment_domain.startswith(settings.SHIBBOLETH_DOMAIN_PREFIX)