936 lines
34 KiB
Python
936 lines
34 KiB
Python
"""
|
|
Certificates API
|
|
|
|
This provides APIs for generating course certificates asynchronously.
|
|
|
|
Other Django apps should use the API functions defined here in this module; other apps should not import the
|
|
certificates models or any other certificates modules.
|
|
"""
|
|
|
|
import logging
|
|
from datetime import datetime
|
|
|
|
from django.contrib.auth import get_user_model
|
|
from django.core.exceptions import ObjectDoesNotExist
|
|
from django.db.models import Q
|
|
from eventtracking import tracker
|
|
from opaque_keys.edx.django.models import CourseKeyField
|
|
from opaque_keys.edx.keys import CourseKey
|
|
from organizations.api import get_course_organization_id
|
|
from pytz import UTC
|
|
|
|
from common.djangoapps.course_modes.models import CourseMode
|
|
from common.djangoapps.student.api import is_user_enrolled_in_course
|
|
from common.djangoapps.student.models import CourseEnrollment
|
|
from lms.djangoapps.branding import api as branding_api
|
|
from lms.djangoapps.certificates.config import AUTO_CERTIFICATE_GENERATION as _AUTO_CERTIFICATE_GENERATION
|
|
from lms.djangoapps.certificates.data import CertificateStatuses
|
|
from lms.djangoapps.certificates.generation_handler import generate_certificate_task as _generate_certificate_task
|
|
from lms.djangoapps.certificates.generation_handler import is_on_certificate_allowlist as _is_on_certificate_allowlist
|
|
from lms.djangoapps.certificates.models import (
|
|
CertificateAllowlist,
|
|
CertificateDateOverride,
|
|
CertificateGenerationConfiguration,
|
|
CertificateGenerationCourseSetting,
|
|
CertificateInvalidation,
|
|
CertificateTemplate,
|
|
CertificateTemplateAsset,
|
|
ExampleCertificateSet,
|
|
GeneratedCertificate,
|
|
)
|
|
from lms.djangoapps.certificates.utils import certificate_status as _certificate_status
|
|
from lms.djangoapps.certificates.utils import certificate_status_for_student as _certificate_status_for_student
|
|
from lms.djangoapps.certificates.utils import get_certificate_url as _get_certificate_url
|
|
from lms.djangoapps.certificates.utils import has_html_certificates_enabled as _has_html_certificates_enabled
|
|
from lms.djangoapps.certificates.utils import should_certificate_be_visible as _should_certificate_be_visible
|
|
from lms.djangoapps.instructor import access
|
|
from lms.djangoapps.utils import _get_key
|
|
from openedx.core.djangoapps.content.course_overviews.api import get_course_overview_or_none
|
|
from openedx.core.djangoapps.content.course_overviews.models import CourseOverview
|
|
from xmodule.data import CertificatesDisplayBehaviors # lint-amnesty, pylint: disable=wrong-import-order
|
|
|
|
log = logging.getLogger("edx.certificate")
|
|
User = get_user_model()
|
|
MODES = GeneratedCertificate.MODES
|
|
|
|
|
|
def _format_certificate_for_user(username, cert):
|
|
"""
|
|
Helper function to serialize a user certificate.
|
|
|
|
Arguments:
|
|
username (unicode): The identifier of the user.
|
|
cert (GeneratedCertificate): a user certificate
|
|
|
|
Returns: dict
|
|
"""
|
|
course_overview = get_course_overview_or_none(cert.course_id)
|
|
if cert.download_url or course_overview:
|
|
return {
|
|
"username": username,
|
|
"course_key": cert.course_id,
|
|
"type": cert.mode,
|
|
"status": cert.status,
|
|
"grade": cert.grade,
|
|
"created": cert.created_date,
|
|
"modified": cert.modified_date,
|
|
"is_passing": CertificateStatuses.is_passing_status(cert.status),
|
|
"is_pdf_certificate": bool(cert.download_url),
|
|
"download_url": (
|
|
cert.download_url
|
|
or get_certificate_url(cert.user.id, cert.course_id, uuid=cert.verify_uuid, user_certificate=cert)
|
|
if cert.status == CertificateStatuses.downloadable
|
|
else None
|
|
),
|
|
"uuid": cert.verify_uuid,
|
|
}
|
|
|
|
return None
|
|
|
|
|
|
def get_certificates_for_user(username):
|
|
"""
|
|
Retrieve certificate information for a particular user.
|
|
|
|
Arguments:
|
|
username (unicode): The identifier of the user.
|
|
|
|
Returns: list
|
|
|
|
Example Usage:
|
|
>>> get_certificates_for_user("bob")
|
|
[
|
|
{
|
|
"username": "bob",
|
|
"course_key": CourseLocator('edX', 'DemoX', 'Demo_Course', None, None),
|
|
"type": "verified",
|
|
"status": "downloadable",
|
|
"download_url": "https://www.example.com/cert.pdf",
|
|
"grade": "0.98",
|
|
"created": 2015-07-31T00:00:00Z,
|
|
"modified": 2015-07-31T00:00:00Z
|
|
}
|
|
]
|
|
|
|
"""
|
|
certs = []
|
|
# Checks if certificates are not None before adding them to list
|
|
for cert in GeneratedCertificate.eligible_certificates.filter(user__username=username).order_by("course_id"):
|
|
formatted_cert = _format_certificate_for_user(username, cert)
|
|
if formatted_cert:
|
|
certs.append(formatted_cert)
|
|
return certs
|
|
|
|
|
|
def get_certificate_for_user(username, course_key, format_results=True):
|
|
"""
|
|
Retrieve certificate information for a particular user for a specific course.
|
|
|
|
Arguments:
|
|
username (unicode): The identifier of the user.
|
|
course_key (CourseKey): A Course Key.
|
|
Returns:
|
|
A dict containing information about the certificate or, optionally,
|
|
the GeneratedCertificate object itself.
|
|
"""
|
|
try:
|
|
cert = GeneratedCertificate.eligible_certificates.get(user__username=username, course_id=course_key)
|
|
except GeneratedCertificate.DoesNotExist:
|
|
return None
|
|
|
|
if format_results:
|
|
return _format_certificate_for_user(username, cert)
|
|
else:
|
|
return cert
|
|
|
|
|
|
def get_certificate_for_user_id(user, course_id):
|
|
"""
|
|
Retrieve certificate information for a user in a specific course.
|
|
|
|
Arguments:
|
|
user (User): A Django User.
|
|
course_id (CourseKey): Course ID
|
|
Returns:
|
|
A GeneratedCertificate object.
|
|
"""
|
|
return GeneratedCertificate.certificate_for_student(user, course_id)
|
|
|
|
|
|
def get_certificates_for_user_by_course_keys(user, course_keys):
|
|
"""
|
|
Retrieve certificate information for a particular user for a set of courses.
|
|
|
|
Arguments:
|
|
user (User)
|
|
course_keys (set[CourseKey])
|
|
|
|
Returns: dict[CourseKey: dict]
|
|
Mapping from course keys to dict of certificate data.
|
|
Course keys for courses for which the user does not have a certificate
|
|
will be omitted.
|
|
"""
|
|
certs = GeneratedCertificate.eligible_certificates.filter(user=user, course_id__in=course_keys)
|
|
return {cert.course_id: _format_certificate_for_user(user.username, cert) for cert in certs}
|
|
|
|
|
|
def get_recently_modified_certificates(course_keys=None, start_date=None, end_date=None, user_ids=None):
|
|
"""
|
|
Returns a QuerySet of GeneratedCertificate objects filtered by the input
|
|
parameters and ordered by modified_date.
|
|
"""
|
|
cert_filter_args = {}
|
|
|
|
if course_keys:
|
|
cert_filter_args["course_id__in"] = course_keys
|
|
|
|
if start_date:
|
|
cert_filter_args["modified_date__gte"] = start_date
|
|
|
|
if end_date:
|
|
cert_filter_args["modified_date__lte"] = end_date
|
|
|
|
if user_ids:
|
|
cert_filter_args["user__id__in"] = user_ids
|
|
|
|
# Include certificates with a CertificateDateOverride modified within the
|
|
# given time range.
|
|
if start_date or end_date:
|
|
certs_with_modified_overrides = get_certs_with_modified_overrides(course_keys, start_date, end_date, user_ids)
|
|
return (
|
|
GeneratedCertificate.objects.filter(**cert_filter_args)
|
|
.union(certs_with_modified_overrides)
|
|
.order_by("modified_date")
|
|
)
|
|
|
|
return GeneratedCertificate.objects.filter(**cert_filter_args).order_by("modified_date")
|
|
|
|
|
|
def get_certs_with_modified_overrides(course_keys=None, start_date=None, end_date=None, user_ids=None):
|
|
"""
|
|
Returns a QuerySet of certificates with a CertificateDateOverride modified
|
|
within the given start_date and end_date. Uses the history table to catch
|
|
deleted overrides too.
|
|
"""
|
|
override_filter_args = {}
|
|
if start_date:
|
|
override_filter_args["history_date__gte"] = start_date
|
|
if end_date:
|
|
override_filter_args["history_date__lte"] = end_date
|
|
|
|
# Get the HistoricalCertificateDateOverrides that have entries within the
|
|
# given date range. We check the history table to catch deleted overrides
|
|
# along with those created / updated
|
|
overrides = CertificateDateOverride.history.filter(**override_filter_args)
|
|
|
|
# Get the associated GeneratedCertificate ids.
|
|
override_cert_ids = overrides.values_list("generated_certificate", flat=True)
|
|
|
|
# Build the args for the GeneratedCertificate query. First, filter by all
|
|
# certs identified in override_cert_ids; then by the other arguments passed,
|
|
# if present.
|
|
cert_filter_args = {"pk__in": override_cert_ids}
|
|
if course_keys:
|
|
cert_filter_args["course_id__in"] = course_keys
|
|
if user_ids:
|
|
cert_filter_args["user__id__in"] = user_ids
|
|
|
|
return GeneratedCertificate.objects.filter(**cert_filter_args)
|
|
|
|
|
|
def generate_certificate_task(user, course_key, generation_mode=None):
|
|
"""
|
|
Create a task to generate a certificate for this user in this course run, if the user is eligible and a certificate
|
|
can be generated.
|
|
|
|
If the allowlist is enabled for this course run and the user is on the allowlist, the allowlist logic will be used.
|
|
Otherwise, the regular course certificate generation logic will be used.
|
|
|
|
Args:
|
|
user: user for whom to generate a certificate
|
|
course_key: course run key for which to generate a certificate
|
|
generation_mode: Used when emitting an events. Options are "self" (implying the user generated the cert
|
|
themself) and "batch" for everything else.
|
|
"""
|
|
return _generate_certificate_task(user, course_key, generation_mode)
|
|
|
|
|
|
def certificate_downloadable_status(student, course_key):
|
|
"""
|
|
Check the student existing certificates against a given course.
|
|
if status is not generating and not downloadable or error then user can view the generate button.
|
|
|
|
Args:
|
|
student (user object): logged-in user
|
|
course_key (CourseKey): ID associated with the course
|
|
|
|
Returns:
|
|
Dict containing student passed status also download url, uuid for cert if available
|
|
"""
|
|
current_status = _certificate_status_for_student(student, course_key)
|
|
|
|
# If the certificate status is an error user should view that status is "generating".
|
|
# On the back-end, need to monitor those errors and re-submit the task.
|
|
|
|
# pylint: disable=simplifiable-if-expression
|
|
response_data = {
|
|
"is_downloadable": False,
|
|
"is_generating": (
|
|
True if current_status["status"] in [CertificateStatuses.generating, CertificateStatuses.error] else False
|
|
),
|
|
"is_unverified": (True if current_status["status"] == CertificateStatuses.unverified else False),
|
|
"download_url": None,
|
|
"uuid": None,
|
|
}
|
|
# pylint: enable=simplifiable-if-expression
|
|
|
|
course_overview = get_course_overview_or_none(course_key)
|
|
|
|
display_behavior_is_valid = (
|
|
course_overview.certificates_display_behavior == CertificatesDisplayBehaviors.END_WITH_DATE
|
|
)
|
|
|
|
if (
|
|
not certificates_viewable_for_course(course_overview)
|
|
and CertificateStatuses.is_passing_status(current_status["status"])
|
|
and display_behavior_is_valid
|
|
and course_overview.certificate_available_date
|
|
):
|
|
response_data["earned_but_not_available"] = True
|
|
response_data["certificate_available_date"] = course_overview.certificate_available_date
|
|
|
|
may_view_certificate = _should_certificate_be_visible(
|
|
course_overview.certificates_display_behavior,
|
|
course_overview.certificates_show_before_end,
|
|
course_overview.has_ended(),
|
|
course_overview.certificate_available_date,
|
|
course_overview.self_paced,
|
|
)
|
|
if current_status["status"] == CertificateStatuses.downloadable and may_view_certificate:
|
|
response_data["is_downloadable"] = True
|
|
response_data["download_url"] = current_status["download_url"] or get_certificate_url(
|
|
student.id, course_key, current_status["uuid"]
|
|
)
|
|
response_data["is_pdf_certificate"] = bool(current_status["download_url"])
|
|
response_data["uuid"] = current_status["uuid"]
|
|
|
|
return response_data
|
|
|
|
|
|
def set_cert_generation_enabled(course_key, is_enabled):
|
|
"""Enable or disable self-generated certificates for a course.
|
|
|
|
There are two "switches" that control whether self-generated certificates
|
|
are enabled for a course:
|
|
|
|
1) Whether the self-generated certificates feature is enabled.
|
|
2) Whether self-generated certificates have been enabled for this particular course.
|
|
|
|
The second flag should be enabled *only* when someone has successfully
|
|
generated example certificates for the course. This helps avoid
|
|
configuration errors (for example, not having a template configured
|
|
for the course installed on the workers). The UI for the instructor
|
|
dashboard enforces this constraint.
|
|
|
|
Arguments:
|
|
course_key (CourseKey): The course identifier.
|
|
|
|
Keyword Arguments:
|
|
is_enabled (boolean): If provided, enable/disable self-generated
|
|
certificates for this course.
|
|
|
|
"""
|
|
CertificateGenerationCourseSetting.set_self_generation_enabled_for_course(course_key, is_enabled)
|
|
cert_event_type = "enabled" if is_enabled else "disabled"
|
|
event_name = ".".join(["edx", "certificate", "generation", cert_event_type])
|
|
tracker.emit(
|
|
event_name,
|
|
{
|
|
"course_id": str(course_key),
|
|
},
|
|
)
|
|
if is_enabled:
|
|
log.info("Enabled self-generated certificates for course '%s'.", str(course_key))
|
|
else:
|
|
log.info("Disabled self-generated certificates for course '%s'.", str(course_key))
|
|
|
|
|
|
def is_certificate_invalidated(student, course_key):
|
|
"""Check whether the certificate belonging to the given student (in given course) has been invalidated.
|
|
|
|
Arguments:
|
|
student (user object): logged-in user
|
|
course_key (CourseKey): The course identifier.
|
|
|
|
Returns:
|
|
Boolean denoting whether the certificate has been invalidated for this learner.
|
|
"""
|
|
log.info(f"Checking if student {student.id} has an invalidated certificate in course {course_key}.")
|
|
|
|
certificate = GeneratedCertificate.certificate_for_student(student, course_key)
|
|
if certificate:
|
|
return CertificateInvalidation.has_certificate_invalidation(student, course_key)
|
|
|
|
return False
|
|
|
|
|
|
def has_self_generated_certificates_enabled(course_key):
|
|
"""Check whether the self-generated certificates feature is enabled for a given course.
|
|
|
|
There are two "switches" that control whether self-generated certificates
|
|
are enabled for a course:
|
|
|
|
1) Whether the self-generated certificates feature is enabled.
|
|
2) Whether self-generated certificates have been enabled for this particular course.
|
|
|
|
Certificates are enabled for a course only when both switches
|
|
are set to True.
|
|
|
|
Arguments:
|
|
course_key (CourseKey): The course identifier.
|
|
|
|
Returns:
|
|
boolean: Whether self-generated certificates are enabled
|
|
for the course.
|
|
|
|
"""
|
|
return (
|
|
CertificateGenerationConfiguration.current().enabled
|
|
and CertificateGenerationCourseSetting.is_self_generation_enabled_for_course(course_key)
|
|
)
|
|
|
|
|
|
def example_certificates_status(course_key):
|
|
"""Check the status of example certificates for a course.
|
|
|
|
This will check the *latest* example certificate task.
|
|
This is generally what we care about in terms of enabling/disabling
|
|
self-generated certificates for a course.
|
|
|
|
Arguments:
|
|
course_key (CourseKey): The course identifier.
|
|
|
|
Returns:
|
|
list
|
|
|
|
Example Usage:
|
|
|
|
>>> from lms.djangoapps.certificates import api as certs_api
|
|
>>> certs_api.example_certificates_status(course_key)
|
|
[
|
|
{
|
|
'description': 'honor',
|
|
'status': 'success',
|
|
'download_url': 'https://www.example.com/abcd/honor_cert.pdf'
|
|
},
|
|
{
|
|
'description': 'verified',
|
|
'status': 'error',
|
|
'error_reason': 'No template found!'
|
|
}
|
|
]
|
|
|
|
"""
|
|
return ExampleCertificateSet.latest_status(course_key)
|
|
|
|
|
|
def has_html_certificates_enabled(course_overview):
|
|
return _has_html_certificates_enabled(course_overview)
|
|
|
|
|
|
def get_certificate_url(user_id=None, course_id=None, uuid=None, user_certificate=None):
|
|
return _get_certificate_url(user_id, course_id, uuid, user_certificate)
|
|
|
|
|
|
def get_active_web_certificate(course, is_preview_mode=None):
|
|
"""
|
|
Retrieves the active web certificate configuration for the specified course
|
|
"""
|
|
certificates = getattr(course, "certificates", {})
|
|
configurations = certificates.get("certificates", [])
|
|
for config in configurations:
|
|
if config.get("is_active") or is_preview_mode:
|
|
return config
|
|
return None
|
|
|
|
|
|
def get_certificate_template(course_key, mode, language):
|
|
"""
|
|
Retrieves the custom certificate template based on course_key, mode, and language.
|
|
"""
|
|
template = None
|
|
# fetch organization of the course
|
|
org_id = get_course_organization_id(course_key)
|
|
|
|
# only consider active templates
|
|
active_templates = CertificateTemplate.objects.filter(is_active=True)
|
|
|
|
if org_id and mode: # get template by org, mode, and key
|
|
org_mode_and_key_templates = active_templates.filter(organization_id=org_id, mode=mode, course_key=course_key)
|
|
template = _get_language_specific_template_or_default(language, org_mode_and_key_templates)
|
|
|
|
# since no template matched that course_key, only consider templates with empty course_key
|
|
empty_course_key_templates = active_templates.filter(course_key=CourseKeyField.Empty)
|
|
if not template and org_id and mode: # get template by org and mode
|
|
org_and_mode_templates = empty_course_key_templates.filter(organization_id=org_id, mode=mode)
|
|
template = _get_language_specific_template_or_default(language, org_and_mode_templates)
|
|
if not template and org_id: # get template by only org
|
|
org_templates = empty_course_key_templates.filter(organization_id=org_id, mode=None)
|
|
template = _get_language_specific_template_or_default(language, org_templates)
|
|
if not template and mode: # get template by only mode
|
|
mode_templates = empty_course_key_templates.filter(organization_id=None, mode=mode)
|
|
template = _get_language_specific_template_or_default(language, mode_templates)
|
|
return template if template else None
|
|
|
|
|
|
def _get_language_specific_template_or_default(language, templates):
|
|
"""
|
|
Returns templates that match passed in language.
|
|
Returns default templates If no language matches, or language passed is None
|
|
"""
|
|
two_letter_language = _get_two_letter_language_code(language)
|
|
|
|
language_or_default_templates = list(
|
|
templates.filter(Q(language=two_letter_language) | Q(language=None) | Q(language=""))
|
|
)
|
|
language_specific_template = _get_language_specific_template(two_letter_language, language_or_default_templates)
|
|
if language_specific_template:
|
|
return language_specific_template
|
|
else:
|
|
return _get_all_languages_or_default_template(language_or_default_templates)
|
|
|
|
|
|
def _get_language_specific_template(language, templates):
|
|
for template in templates:
|
|
if template.language == language:
|
|
return template
|
|
return None
|
|
|
|
|
|
def _get_all_languages_or_default_template(templates):
|
|
"""
|
|
Returns the first template that isn't language specific
|
|
"""
|
|
for template in templates:
|
|
if template.language == "":
|
|
return template
|
|
|
|
return templates[0] if templates else None
|
|
|
|
|
|
def _get_two_letter_language_code(language_code):
|
|
"""
|
|
Shortens language to only first two characters (e.g. es-419 becomes es)
|
|
This is needed because Catalog returns locale language which is not always a 2 letter code.
|
|
"""
|
|
if language_code is None:
|
|
return None
|
|
elif language_code == "":
|
|
return ""
|
|
else:
|
|
return language_code[:2]
|
|
|
|
|
|
def get_asset_url_by_slug(asset_slug):
|
|
"""
|
|
Returns certificate template asset url for given asset_slug.
|
|
"""
|
|
asset_url = ""
|
|
try:
|
|
template_asset = CertificateTemplateAsset.objects.get(asset_slug=asset_slug)
|
|
asset_url = template_asset.asset.url
|
|
except CertificateTemplateAsset.DoesNotExist:
|
|
pass
|
|
return asset_url
|
|
|
|
|
|
def get_certificate_header_context(is_secure=True):
|
|
"""
|
|
Return data to be used in Certificate Header,
|
|
data returned should be customized according to the site configuration.
|
|
"""
|
|
data = dict(
|
|
logo_src=branding_api.get_logo_url(is_secure),
|
|
logo_url=branding_api.get_base_url(is_secure),
|
|
)
|
|
|
|
return data
|
|
|
|
|
|
def get_certificate_footer_context():
|
|
"""
|
|
Return data to be used in Certificate Footer,
|
|
data returned should be customized according to the site configuration.
|
|
"""
|
|
data = {}
|
|
|
|
# get Terms of Service and Honor Code page url
|
|
terms_of_service_and_honor_code = branding_api.get_tos_and_honor_code_url()
|
|
if terms_of_service_and_honor_code != branding_api.EMPTY_URL:
|
|
data.update({"company_tos_url": terms_of_service_and_honor_code})
|
|
|
|
# get Privacy Policy page url
|
|
privacy_policy = branding_api.get_privacy_url()
|
|
if privacy_policy != branding_api.EMPTY_URL:
|
|
data.update({"company_privacy_url": privacy_policy})
|
|
|
|
# get About page url
|
|
about = branding_api.get_about_url()
|
|
if about != branding_api.EMPTY_URL:
|
|
data.update({"company_about_url": about})
|
|
|
|
return data
|
|
|
|
|
|
def certificates_viewable_for_course(course):
|
|
"""
|
|
Returns True if certificates are viewable for any student enrolled in the course, False otherwise.
|
|
|
|
Arguments:
|
|
course (CourseOverview or course block): The course to check if certificates are viewable
|
|
|
|
Returns:
|
|
boolean: whether the certificates are viewable or not
|
|
"""
|
|
|
|
# The CourseOverview contains validation logic on the certificates_display_behavior and certificate_available_date
|
|
# fields. Thus, we prefer to use the CourseOverview, but will fall back to the course in case the CourseOverview is
|
|
# not available.
|
|
if not isinstance(course, CourseOverview):
|
|
course_overview = get_course_overview_or_none(course.id)
|
|
if course_overview:
|
|
course = course_overview
|
|
|
|
return _should_certificate_be_visible(
|
|
course.certificates_display_behavior,
|
|
course.certificates_show_before_end,
|
|
course.has_ended(),
|
|
course.certificate_available_date,
|
|
course.self_paced,
|
|
)
|
|
|
|
|
|
def get_allowlisted_users(course_key):
|
|
"""
|
|
Return the users who are on the allowlist for this course run
|
|
"""
|
|
return User.objects.filter(certificateallowlist__course_id=course_key, certificateallowlist__allowlist=True)
|
|
|
|
|
|
def create_or_update_certificate_allowlist_entry(user, course_key, notes, enabled=True):
|
|
"""
|
|
Update-or-create an allowlist entry for a student in a given course-run.
|
|
"""
|
|
certificate_allowlist, created = CertificateAllowlist.objects.update_or_create(
|
|
user=user,
|
|
course_id=course_key,
|
|
defaults={
|
|
"allowlist": enabled,
|
|
"notes": notes,
|
|
},
|
|
)
|
|
|
|
log.info(f"Updated the allowlist of course {course_key} with student {user.id} and enabled={enabled}")
|
|
|
|
return certificate_allowlist, created
|
|
|
|
|
|
def remove_allowlist_entry(user, course_key):
|
|
"""
|
|
Removes an allowlist entry for a user in a given course-run. If a certificate exists for the student in the
|
|
course-run we will also attempt to invalidate the it before removing them from the allowlist.
|
|
|
|
Returns the result of the removal operation as a bool.
|
|
"""
|
|
log.info(f"Removing student {user.id} from the allowlist in course {course_key}")
|
|
deleted = False
|
|
|
|
allowlist_entry = get_allowlist_entry(user, course_key)
|
|
if allowlist_entry:
|
|
certificate = get_certificate_for_user(user.username, course_key, False)
|
|
if certificate:
|
|
log.info(f"Invalidating certificate for student {user.id} in course {course_key} before allowlist removal.")
|
|
certificate.invalidate(source="allowlist_removal")
|
|
|
|
log.info(f"Removing student {user.id} from the allowlist in course {course_key}.")
|
|
allowlist_entry.delete()
|
|
deleted = True
|
|
|
|
return deleted
|
|
|
|
|
|
def get_allowlist_entry(user, course_key):
|
|
"""
|
|
Retrieves and returns an allowlist entry for a given learner and course-run.
|
|
"""
|
|
log.info(f"Attempting to retrieve an allowlist entry for student {user.id} in course {course_key}.")
|
|
try:
|
|
allowlist_entry = CertificateAllowlist.objects.get(user=user, course_id=course_key)
|
|
except ObjectDoesNotExist:
|
|
log.warning(f"No allowlist entry found for student {user.id} in course {course_key}.")
|
|
return None
|
|
|
|
return allowlist_entry
|
|
|
|
|
|
def is_on_allowlist(user, course_key):
|
|
"""
|
|
Determines if a learner has an active allowlist entry for a given course-run.
|
|
"""
|
|
log.info(f"Checking if student {user.id} is on the allowlist in course {course_key}")
|
|
return _is_on_certificate_allowlist(user, course_key)
|
|
|
|
|
|
def can_be_added_to_allowlist(user, course_key):
|
|
"""
|
|
Determines if a student is able to be added to the allowlist in a given course-run.
|
|
"""
|
|
log.info(f"Checking if student {user.id} in course {course_key} can be added to the allowlist.")
|
|
|
|
if not is_user_enrolled_in_course(user, course_key):
|
|
log.info(f"Student {user.id} is not enrolled in course {course_key}")
|
|
return False
|
|
|
|
if is_certificate_invalidated(user, course_key):
|
|
log.info(f"Student {user.id} is on the certificate invalidation list for course {course_key}")
|
|
return False
|
|
|
|
if is_on_allowlist(user, course_key):
|
|
log.info(f"Student {user.id} already appears on allowlist in course {course_key}")
|
|
return False
|
|
|
|
return True
|
|
|
|
|
|
def create_certificate_invalidation_entry(certificate, user_requesting_invalidation, notes):
|
|
"""
|
|
Invalidates a certificate with the given certificate id.
|
|
"""
|
|
log.info(f"Creating a certificate invalidation entry linked to certificate with id {certificate.id}.")
|
|
certificate_invalidation, __ = CertificateInvalidation.objects.update_or_create(
|
|
generated_certificate=certificate,
|
|
defaults={
|
|
"active": True,
|
|
"invalidated_by": user_requesting_invalidation,
|
|
"notes": notes,
|
|
},
|
|
)
|
|
|
|
return certificate_invalidation
|
|
|
|
|
|
def get_certificate_invalidation_entry(certificate):
|
|
"""
|
|
Retrieves and returns an certificate invalidation entry for a given certificate id.
|
|
"""
|
|
log.info(f"Attempting to retrieve certificate invalidation entry for certificate with id {certificate.id}.")
|
|
try:
|
|
certificate_invalidation_entry = CertificateInvalidation.objects.get(generated_certificate=certificate)
|
|
except ObjectDoesNotExist:
|
|
log.warning(f"No certificate invalidation found linked to certificate with id {certificate.id}.")
|
|
return None
|
|
|
|
return certificate_invalidation_entry
|
|
|
|
|
|
def get_allowlist(course_key):
|
|
"""
|
|
Return the certificate allowlist for the given course run
|
|
"""
|
|
return CertificateAllowlist.get_certificate_allowlist(course_key)
|
|
|
|
|
|
def get_enrolled_allowlisted_users(course_key):
|
|
"""
|
|
Get all users who:
|
|
- are enrolled in this course run
|
|
- are allowlisted in this course run
|
|
"""
|
|
users = CourseEnrollment.objects.users_enrolled_in(course_key)
|
|
return users.filter(certificateallowlist__course_id=course_key, certificateallowlist__allowlist=True)
|
|
|
|
|
|
def get_enrolled_allowlisted_not_passing_users(course_key):
|
|
"""
|
|
Get all users who:
|
|
- are enrolled in this course run
|
|
- are allowlisted in this course run
|
|
- do not have a course certificate with a passing status
|
|
"""
|
|
users = get_enrolled_allowlisted_users(course_key)
|
|
return users.exclude(
|
|
generatedcertificate__course_id=course_key, generatedcertificate__status__in=CertificateStatuses.PASSED_STATUSES
|
|
)
|
|
|
|
|
|
def certificate_info_for_user(user, course_id, grade, user_is_allowlisted, user_certificate):
|
|
"""
|
|
Returns the certificate info for a user for grade report.
|
|
"""
|
|
certificate_is_delivered = "N"
|
|
certificate_type = "N/A"
|
|
status = _certificate_status(user_certificate)
|
|
certificate_generated = status["status"] == CertificateStatuses.downloadable
|
|
course_overview = get_course_overview_or_none(course_id)
|
|
if not course_overview:
|
|
return None
|
|
can_have_certificate = _should_certificate_be_visible(
|
|
course_overview.certificates_display_behavior,
|
|
course_overview.certificates_show_before_end,
|
|
course_overview.has_ended(),
|
|
course_overview.certificate_available_date,
|
|
course_overview.self_paced,
|
|
)
|
|
enrollment_mode, __ = CourseEnrollment.enrollment_mode_for_user(user, course_id)
|
|
mode_is_verified = enrollment_mode in CourseMode.VERIFIED_MODES
|
|
user_is_verified = grade is not None and mode_is_verified
|
|
|
|
eligible_for_certificate = "Y" if (user_is_allowlisted or user_is_verified or certificate_generated) else "N"
|
|
|
|
if certificate_generated and can_have_certificate:
|
|
certificate_is_delivered = "Y"
|
|
certificate_type = status["mode"]
|
|
|
|
return [eligible_for_certificate, certificate_is_delivered, certificate_type]
|
|
|
|
|
|
def certificate_status_for_student(student, course_id):
|
|
"""This returns a dictionary with a key for status, and other information."""
|
|
return _certificate_status_for_student(student, course_id)
|
|
|
|
|
|
def auto_certificate_generation_enabled():
|
|
return _AUTO_CERTIFICATE_GENERATION.is_enabled()
|
|
|
|
|
|
def _enabled_and_instructor_paced(course):
|
|
if auto_certificate_generation_enabled():
|
|
return not course.self_paced
|
|
return False
|
|
|
|
|
|
def can_show_certificate_available_date_field(course):
|
|
return _enabled_and_instructor_paced(course)
|
|
|
|
|
|
def can_show_certificate_message(course, student, course_grade, certificates_enabled_for_course):
|
|
"""
|
|
Returns True if a course certificate message can be shown
|
|
"""
|
|
auto_cert_gen_enabled = auto_certificate_generation_enabled()
|
|
has_active_enrollment = CourseEnrollment.is_enrolled(student, course.id)
|
|
certificates_are_viewable = certificates_viewable_for_course(course)
|
|
is_beta_tester = access.is_beta_tester(student, course.id)
|
|
has_passed_or_is_allowlisted = _has_passed_or_is_allowlisted(course, student, course_grade)
|
|
|
|
return (
|
|
(auto_cert_gen_enabled or certificates_enabled_for_course)
|
|
and has_active_enrollment
|
|
and certificates_are_viewable
|
|
and has_passed_or_is_allowlisted
|
|
and (not is_beta_tester)
|
|
)
|
|
|
|
|
|
def _course_uses_available_date(course):
|
|
"""Returns if the course has an certificate_available_date set and that it should be used"""
|
|
display_behavior_is_valid = course.certificates_display_behavior == CertificatesDisplayBehaviors.END_WITH_DATE
|
|
|
|
return (
|
|
can_show_certificate_available_date_field(course)
|
|
and course.certificate_available_date
|
|
and display_behavior_is_valid
|
|
)
|
|
|
|
|
|
def available_date_for_certificate(course, certificate) -> datetime:
|
|
"""
|
|
Returns the available date to use with a certificate
|
|
|
|
Arguments:
|
|
course (CourseOverview or course block): The course we're checking
|
|
certificate (GeneratedCertificate): The certificate we're getting the date for
|
|
"""
|
|
if _course_uses_available_date(course):
|
|
return course.certificate_available_date
|
|
return certificate.modified_date
|
|
|
|
|
|
def display_date_for_certificate(course, certificate):
|
|
"""
|
|
Returns the display date that a certificate should display.
|
|
|
|
Arguments:
|
|
course (CourseOverview or course block): The course we're getting the date for
|
|
Returns:
|
|
datetime.date
|
|
"""
|
|
try:
|
|
if certificate.date_override:
|
|
return certificate.date_override.date
|
|
except ObjectDoesNotExist:
|
|
pass
|
|
|
|
if _course_uses_available_date(course) and course.certificate_available_date < datetime.now(UTC):
|
|
return course.certificate_available_date
|
|
|
|
return certificate.modified_date
|
|
|
|
|
|
def is_valid_pdf_certificate(cert_data):
|
|
return cert_data.cert_status == CertificateStatuses.downloadable and cert_data.download_url
|
|
|
|
|
|
def _has_passed_or_is_allowlisted(course, student, course_grade):
|
|
"""
|
|
Returns True if the student has passed this course run, or is on the allowlist for this course run
|
|
"""
|
|
is_allowlisted = is_on_allowlist(student, course.id)
|
|
has_passed = course_grade and course_grade.passed
|
|
|
|
return has_passed or is_allowlisted
|
|
|
|
|
|
def invalidate_certificate(user_id, course_key_or_id, source):
|
|
"""
|
|
Invalidate the user certificate in a given course if it exists and the user is not on the allowlist for this
|
|
course run.
|
|
|
|
This function is called in services.py and signals.py within the certificates folder. As of now,
|
|
The call in services.py occurs when an exam attempt is rejected in the legacy exams backend, edx-proctoring.
|
|
The call in signals.py is occurs when an exam attempt is rejected in the newer exams backend, edx-exams.
|
|
"""
|
|
course_key = _get_key(course_key_or_id, CourseKey)
|
|
if _is_on_certificate_allowlist(user_id, course_key):
|
|
log.info(f"User {user_id} is on the allowlist for {course_key}. The certificate will not be invalidated.")
|
|
return False
|
|
|
|
try:
|
|
generated_certificate = GeneratedCertificate.objects.get(user=user_id, course_id=course_key)
|
|
generated_certificate.invalidate(source=source)
|
|
except ObjectDoesNotExist:
|
|
log.warning(
|
|
"Invalidation failed because a certificate for user %d in course %s does not exist.", user_id, course_key
|
|
)
|
|
return False
|
|
|
|
return True
|
|
|
|
|
|
def clear_pii_from_certificate_records_for_user(user):
|
|
"""
|
|
Utility function to remove PII from certificate records when a learner's account is being retired. Used by the
|
|
`AccountRetirementView` in the `user_api` Django app (invoked by the /api/user/v1/accounts/retire endpoint).
|
|
|
|
The update is performed using a bulk SQL update via the Django ORM. This will not trigger the GeneratedCertificate
|
|
model's custom `save()` function, nor fire any Django signals (which is desired at the time of writing). There is
|
|
nothing to update in our external systems by this update.
|
|
|
|
Args:
|
|
user (User): The User instance of the learner actively being retired.
|
|
|
|
Returns:
|
|
None
|
|
"""
|
|
GeneratedCertificate.objects.filter(user=user).update(name="")
|