Add import-to-contract-courserun workflow (#3057)

Author: jkachel

b2b/api.py

@@ -33,7 +33,7 @@
 )
 from cms.api import get_home_page
 from courses.constants import UAI_COURSEWARE_ID_PREFIX
-from courses.models import Course, CourseRun
+from courses.models import Course, CourseRun, Department
 from ecommerce.constants import (
     DISCOUNT_TYPE_FIXED_PRICE,
     PAYMENT_TYPE_SALES,
@@ -76,27 +76,111 @@ def ensure_b2b_organization_index() -> OrganizationIndexPage:
     return org_index_page
 
 
-def import_and_create_contract_run(contract: ContractPage, course_run_id: str):
+def import_and_create_contract_run(  # noqa: PLR0913
+    contract: ContractPage,
+    course_run_id: str,
+    departments: list[Department | str],
+    *,
+    live: bool = True,
+    use_specific_course: str | None = None,
+    create_depts: bool = False,
+    block_countries: list[str] | None = None,
+    create_cms_page: bool = True,
+    publish_cms_page: bool = False,
+    include_in_learn_catalog: bool = False,
+    ingest_content_files_for_ai: bool = True,
+    skip_edx: bool = False,
+    require_designated_source_run: bool = False,
+):
     """
     Create a contract run for the given course, importing it from edX if necessary.
 
-    Check for the specified course run. If it exists, create the contract run in
-    the usual fashion. If it doesn't, check for it in edX and import it into
-    MITx Online first, then create the contract run.
-
-    If the specified run is imported, it will have the "is_source_run" flag set.
+    Wraps the create_contract_run function in some logic to check for the specified
+    course, and then import it. If the course is imported from edX, this will set
+    a few flags to reasonable values and call the import_courserun_from_edx
+    function, then call create_contract_run using the imported run as the source
+    course. If the course is already in the system, this just calls
+    create_contract_run with the source run and the use_specific_course flag set
+    to force it to use the specified run.
+
+    The kwargs combine the set from import_courserun_from_edx and
+    create_contract_run. Some of the defaults are different, owning to the use case
+    for this function. Those differences are:
+    - You must pass in a list of departments.
+    - By default, the live flag is set to True.
+    - Learn AI ingestion will be set to True.
+    - require_designated_source_run is set to False. (We assume you want the
+      specified course, regardless of the source flag.)
+
+    In addition, if the course is imported, the corresponding run that is created
+    for it will have the is_source_run flag set to True. This cannot be
+    overridden. By using this function, we are assuming you really want the
+    specified run as the source.
+
+    This won't pass a price to the import call, so the imported run won't have a
+    product. This _will_ set a price on the contract run, because the contract
+    run must have a price, even if that price is zero. The price will be whatever
+    is specified in the contract (or zero).
+
+    Calling this function will result in a contract course run being created. If
+    the course is imported, then you will end up with a course with two runs:
+    the one that was imported and the new contract run.
 
     Args:
         contract (ContractPage): The contract to create the run for.
         course_run_id (str): The readable ID for the source course run.
-    Keyword Args:
+        departments (list[Department | str]): Departments to add to the new course.
+    Keyword Args (passed to import_courserun_from_edx and create_contract_run):
+        live (bool): Make the new course run live, and the course if one is created.
+        use_specific_course (str|None): Readable ID of a specific course to use as the base course.
+        create_depts (bool): Create departments.
+        block_countries (list[str] | None): Country codes to add to the block list for the course.
+        create_cms_page (bool): Create a CMS page for the course. Only applies if a course is being created.
+        publish_cms_page (bool): Publish the new CMS page. Only takes effect if creating a CMS page.
+        include_in_learn_catalog (bool): Set the "include_in_learn_catalog" flag on the new page.
+        ingest_content_files_for_ai (bool): Set the "ingest_content_files_for_ai" flag on the new page.
         skip_edx (bool): Don't try to create a course run in edX.
         require_designated_source_run (bool): Require a flagged source run.
     Returns:
         CourseRun: The created CourseRun object.
         Product: The created Product object.
     """
 
+    run_qs = CourseRun.objects.filter(courseware_id=course_run_id)
+
+    if run_qs.exists():
+        run = run_qs.get()
+    else:
+        from courses.api import import_courserun_from_edx
+
+        rundata = import_courserun_from_edx(
+            course_key=course_run_id,
+            live=live,
+            use_specific_course=use_specific_course,
+            departments=departments,
+            create_depts=create_depts,
+            block_countries=block_countries,
+            price=None,
+            create_cms_page=create_cms_page,
+            publish_cms_page=publish_cms_page,
+            include_in_learn_catalog=include_in_learn_catalog,
+            ingest_content_files_for_ai=ingest_content_files_for_ai,
+            is_source_run=True,
+        )
+
+        if not rundata:
+            msg = f"Import and create contract run for {course_run_id} failed - could not import from edX."
+            raise ValueError(msg)
+
+        run = rundata[0]
+
+    return create_contract_run(
+        contract,
+        run.course,
+        skip_edx=skip_edx,
+        require_designated_source_run=require_designated_source_run,
+    )
+
 
 def create_contract_run(
     contract: ContractPage,

b2b/management/commands/b2b_courseware.py

@@ -9,7 +9,7 @@
 
 from django.core.management import BaseCommand, CommandError
 
-from b2b.api import create_contract_run
+from b2b.api import create_contract_run, import_and_create_contract_run
 from b2b.models import ContractPage, ContractProgramItem
 from courses.api import resolve_courseware_object_from_id
 from courses.models import CourseRun
@@ -27,13 +27,17 @@ class Command(BaseCommand):
 Specifying courseware: You must specify one courseware item (of any type). You can specify more than one by adding "--also <courseware id>" to the end of the command. You can repeat this as many times as necessary.
 
 To add courseware:
-   b2b_courseware add [--no-create-runs] [--force] contract courseware [--also courseware] [--also courseware...]
+   b2b_courseware add [--import <departments>] [--no-create-runs] [--force] <contract> <courseware> [--also <courseware>] [--also <courseware>...]
 
 Example: b2b_courseware add contract-100-101 program-v1:UAI+Fundamentals --also course-v1:UAI_C100+14.314x+2025_C101
 
+Specifying "--import" will attempt to import the course run from edX if it can't be found in MITx Online. A corresponding course and course run will be created in MITx Online, and the run will be flagged as a source run. A new contract run will be created for the contract specified. The "--import" flag is ignored if a course is specified, as edX only has course runs. The "--import" flag is also ignored if a program is specified, as the command won't be able to determine what to import (again, because programs have courses, and edX doesn't have courses).
+
+If "--import" is specified, it expects a list of departments for the new courses to be added to. This should be a list of names, separated by commas. You must specify at least one department as courses must belong to at least one department. The departments must exist; it won't create them for you.
+
 Specifying a course run will attach it to the contract unless the contract is already attached to a contract. Specify "--force" to override any existing contract attachment.
 
-Specifying a course will attempt to create a course run for the contract for the specified course. It will try to create a course run in edX as well unless "--no-create-runs" is specified.
+Specifying a course will attempt to create a course run for the contract for the specified course. It will try to create a course run in edX as well unless "--no-create-runs" is specified. This flag is ignored if "--import" is specified.
 
 Specifying a program will iterate through the program's courses and create runs for each. It will also link the program to the contract.
 
@@ -114,6 +118,12 @@ def add_arguments(self, parser):
             dest="force",
             action="store_true",
         )
+        add_subparser.add_argument(
+            "--import",
+            help="Attempt to import course runs specified into the department(s), if they don't exist in MITx Online.",
+            dest="can_import",
+            type=str,
+        )
 
         remove_subparser = subparsers.add_parser(
             "remove",
@@ -128,15 +138,57 @@ def add_arguments(self, parser):
 
         return super().add_arguments(parser)
 
-    def handle_add(self, contract, coursewares, **kwargs):
+    def handle_add(self, contract, coursewares, **kwargs):  # noqa: PLR0915, C901
         """Handle the add subcommand."""
 
         create_runs = kwargs.pop("create_runs")
         force_associate = kwargs.pop("force")
+        can_import = kwargs.pop("import")
 
         managed = skipped = 0
 
+        if can_import:
+            # Get the courseware IDs we got passed in that weren't matched to
+            # system records. We will try to pull these in from edX.
+
+            importable_ids = [kwargs.get("courseware", "")]
+            importable_extras = kwargs.get("additional_courseware")
+            if importable_extras:
+                importable_ids.extend(importable_extras)
+
+            non_importable_ids = [
+                courseware.readable_id for courseware in coursewares if courseware
+            ]
+
+            for importable_id in importable_ids:
+                if importable_id in non_importable_ids:
+                    continue
+
+                self.stdout.write(f"Attempting to import {importable_id} from edX...")
+
+                imported_run, _ = import_and_create_contract_run(
+                    contract=contract,
+                    course_run_id=importable_id,
+                    departments=can_import.split(sep=","),
+                    create_cms_page=True,
+                )
+
+                if not imported_run:
+                    self.stdout.write(
+                        self.style.ERROR(f"Importing {importable_id} failed. Skipping")
+                    )
+                    continue
+
+                self.stdout.write(
+                    self.style.SUCCESS(
+                        f"Importing {importable_id} succeeded: {imported_run} created."
+                    )
+                )
+
         for courseware in coursewares:
+            if not courseware:
+                continue
+
             if courseware.is_program:
                 # If you're specifying a program, we will always make new runs
                 # since we won't be able to tell which existing ones to use.
@@ -286,8 +338,8 @@ def handle(self, *args, **kwargs):  # noqa: ARG002
         """Dispatch the requested task."""
 
         contract_id = kwargs.pop("contract")
-        courseware_id = kwargs.pop("courseware")
-        additional_courseware_ids = kwargs.pop("additional_courseware")
+        courseware_id = kwargs.get("courseware", "")
+        additional_courseware_ids = kwargs.get("additional_courseware")
         subcommand = kwargs.pop("subcommand")
 
         if contract_id.isdecimal():

courses/api.py

@@ -1141,6 +1141,7 @@ def import_courserun_from_edx(  # noqa: C901, PLR0913
     publish_cms_page: bool = False,
     include_in_learn_catalog: bool = False,
     ingest_content_files_for_ai: bool = False,
+    is_source_run: bool = False,
 ):
     """
     Import a course run from edX.
@@ -1182,14 +1183,15 @@ def import_courserun_from_edx(  # noqa: C901, PLR0913
     - publish_cms_page (bool): Publish the new CMS page. Only takes effect if creating a CMS page.
     - include_in_learn_catalog (bool): Set the "include_in_learn_catalog" flag on the new page.
     - ingest_content_files_for_ai (bool): Set the "ingest_content_files_for_ai" flag on the new page.
+    - is_source_run (bool): Set the "is_source_run" flag on the course run to designate it as a B2B source course.
     Returns:
     tuple of (CourseRun, CoursePage|None, Product|None) - relevant objects for the imported run
     """
 
     if CourseRun.objects.filter(courseware_id=course_key).exists():
         return False
 
-    processed_course_key = CourseKey(course_key)
+    processed_course_key = CourseKey.from_string(course_key)
 
     edx_course_detail = get_edx_api_course_detail_client()
 
@@ -1198,7 +1200,7 @@ def import_courserun_from_edx(  # noqa: C901, PLR0913
         username=settings.OPENEDX_SERVICE_WORKER_USERNAME,
     )
 
-    processed_run_key = CourseKey(edx_course_run.course_id)
+    processed_run_key = CourseKey.from_string(edx_course_run.course_id)
 
     if use_specific_course:
         root_course = Course.objects.get(readable_id=use_specific_course)
@@ -1223,11 +1225,12 @@ def import_courserun_from_edx(  # noqa: C901, PLR0913
 
             for department in departments:
                 if isinstance(department, str) and create_depts:
-                    dept = Department.objects.get_or_create(name=department)
-                else:
+                    dept, _ = Department.objects.get_or_create(name=department)
+                    dept.save()
+                elif isinstance(department, Department):
                     dept = department
 
-                root_course.departments.add(dept)
+                root_course.departments.add(dept.id)
 
     new_run = CourseRun.objects.create(
         course=root_course,
@@ -1240,14 +1243,15 @@ def import_courserun_from_edx(  # noqa: C901, PLR0913
         title=edx_course_run.name,
         live=live,
         is_self_paced=edx_course_run.is_self_paced(),
+        is_source_run=is_source_run,
         courseware_url_path=urljoin(
             settings.OPENEDX_COURSE_BASE_URL,
             f"/{edx_course_run.course_id}/course",
         ),
     )
 
     course_page = None
-    if create_cms_page:
+    if create_cms_page and not use_specific_course:
         course_page = create_default_courseware_page(
             courseware=new_run.course,
             live=publish_cms_page,