Update b2b docs (#3040)

Author: ChristopherChudzicki

b2b/management/commands/b2b_courseware.py

@@ -147,7 +147,15 @@ def handle_add(self, contract, coursewares, **kwargs):
                     )
                 )
 
-                prog_add, prog_skip = contract.add_program_courses(courseware)
+                prog_add, prog_skip, prog_no_source = contract.add_program_courses(
+                    courseware
+                )
+                if prog_no_source > 0:
+                    self.stdout.write(
+                        self.style.WARNING(
+                            f"Program '{courseware.readable_id}' has {prog_no_source} courses with no source runs; cannot create contract runs for these courses."
+                        )
+                    )
                 contract.save()
                 managed += prog_add
                 skipped += prog_skip

b2b/models.py

@@ -377,18 +377,25 @@ def add_program_courses(self, program):
         - program (courses.Program): the program to add
 
         Returns:
-        - tuple, courses created and skipped
+        - tuple: Tuple with three integers:
+            - number of course runs created
+            - number of course runs skipped (already existed)
+            - number of courses with no source run
         """
 
         from b2b.api import create_contract_run
 
-        managed = 0
-        skipped = 0
-
         # Clear any cached properties to ensure fresh data
         if hasattr(program, "_courses_with_requirements_data"):
             delattr(program, "_courses_with_requirements_data")
 
+        managed = 0
+        skipped_run_creation = 0
+        no_source = program.courses_qset.exclude(
+            models.Q(courseruns__is_source_run=True)
+            | models.Q(courseruns__run_tag="SOURCE")
+        ).count()
+
         for course in program.courses_qset.filter(
             models.Q(courseruns__is_source_run=True)
             | models.Q(courseruns__run_tag="SOURCE")
@@ -397,11 +404,11 @@ def add_program_courses(self, program):
                 create_contract_run(self, course)
                 managed += 1
             except TargetCourseRunExistsError:  # noqa: PERF203
-                skipped += 1
+                skipped_run_creation += 1
 
         self.programs.add(program)
 
-        return (managed, skipped)
+        return (managed, skipped_run_creation, no_source)
 
     class Meta:
         """Meta options for the ContractPage."""

b2b/models_test.py

@@ -24,10 +24,11 @@ def test_add_program_courses_to_contract(mocker):
 
     program.refresh_from_db()
 
-    created, skipped = contract.add_program_courses(program)
+    created, skipped, no_source = contract.add_program_courses(program)
 
     assert created == 3
     assert skipped == 0
+    assert no_source == 0
 
     contract.save()
     contract.refresh_from_db()
@@ -40,10 +41,11 @@ def test_add_program_courses_to_contract(mocker):
     program.save()
     program.refresh_from_db()
 
-    created, skipped = contract.add_program_courses(program)
+    created, skipped, no_source = contract.add_program_courses(program)
 
     assert created == 1
     assert skipped == 3
+    assert no_source == 0
 
     contract.save()
     contract.refresh_from_db()

docs/source/configuration/b2b.rst

@@ -14,6 +14,7 @@ The management commands you will need to use are:
 
 * ``b2b_contracts`` - manages organizations and contracts
 * ``b2b_list`` - lists data about B2B resources
+* ``b2b_courseware`` - manages courseware assignments to contracts
 
 Quick Setup
 -----------
@@ -27,13 +28,18 @@ This is how UAI contracts that have SSO integration with the host organization a
 
 
 #. Create a contract with a new organization:
-   ``b2b_contract create UniversityX "UniversityX Contract" sso --description "Test uncapped SSO contract"``
+   ``b2b_contract create "University X" "Contract Name" sso --description "Test uncapped SSO contract"``
+
+   - if organization does not yet exist, add ``--create`` and ``--org-key <org key>`` to set the organization key
 #. List the details about your new organization:
    ``b2b_list organizations``
 #. List the details about your new contract: *(You'll need the ID from the output for the next step.)*
    ``b2b_list contracts``
-#. Add the course to the contract. This will also create a course run for the course:
-   ``b2b_contract courseware <contract ID> <course readable ID>``
+#. Add courseware (course or program) to the contract. This will also create a course run for the course:
+   ``b2b_courseware add <contract ID> <courseware readable ID>``
+
+   - Courses must have a *source run* in order to create contract-specific runs; see the "Courseware Setup in edX" section below for more details.
+   - Program readable_ids must begin with ``program-v1``.
 #. List the details about the contract's courseware:
    ``b2b_list courseware --contract <contract ID>``
 
@@ -52,7 +58,7 @@ This is how a B2B contract would be set up typically.
 #. List the details about your new contract: *(You'll need the ID from the output for the next step.)*
    ``b2b_list contracts``
 #. Add the course to the contract. This will also create a course run for the course:
-   ``b2b_contract courseware <contract ID> <course readable ID>``
+   ``b2b_courseware add <contract ID> <course readable ID>``
 #. List the details about the contract's courseware:
    ``b2b_list courseware --contract <contract ID>``
 #. Get the enrollment codes for the contract:
@@ -183,9 +189,17 @@ Courseware Setup in edX
 
 B2B courses in edX should be set up in a particular fashion, both to make sure we can identify them within edX easily, and to allow the system to automatically create runs for new contracts.
 
-Each B2B course starts with a source course. Usually, these are separate courses and runs, but not always. If you're creating a new course, it should be created in edX with the organization ``UAI_SOURCE`` and the run tag ``SOURCE``. A corresponding course run in MITx Online should also be created. The ``import_courserun`` command can be used to help facilitate this. If you want to use an existing course, you should create a ``SOURCE`` run for it from the run you want to use as the source course in edX.
+Each B2B course starts with a source course and courserun. Usually, these are separate courses and runs, but not always.
+
+
+* If using a separate course & courserun,  it should be created in edX with the organization ``UAI_SOURCE`` and run tag ``SOURCE``. The ``import courserun`` command can assist in importing the course from OpenEdx into MITxOnline.
+* If reusing an existing course, create a new courserunw with run tag ``SOURCE``.
+
+
+**In both cases:** The courserun should have the `is_source_run` flag set to `True` in MITxOnline (this can be done via Django Admin).
+
+When associating a course or program with a contract, the ``b2b_contract courseware`` command will try to create a contract-specific run for each source course (either the one you've specified or the ones that are in the specified program).
 
-When associating a course or program with a contract, the ``b2b_contract courseware`` command will try to create a contract-specific run for each source course (either the one you've specified or the ones that are in the specified program). It does this by trying to find an appropriate source course run for the course in MITx Online. It will look first for a course run with the run tag ``SOURCE`` - if it can't find this, it will use whatever the first course run is in database order. **This is probably not what you want** - you should try to have a ``SOURCE`` course run if at all possible.
 
 Course runs will be created using the start/end date of the contract, if those dates are set. If the contract is open-ended, the runs will be created with the current time/date as the course and enrollment start date and no end date. The runs will be created with the organization set to ``UAI_`` and the organization key set in the org record, and the run key will be set to the current year, ``C``, and the ID of the new contract.