feat: Add enrollments v2 list endpoint

[brianjbuck-wgu]

Description

Migrates Enrollments endpoint to use in the instructor dashboard MFE:

1. New list_course_enrollments endpoint — A new POST /courses/{course_id}/instructor/api/list_course_enrollments endpoint that returns a paginated, searchable list of all active course enrollments. Returns user data (username, email, first_name, last_name) with total count and pagination metadata.

Changes:

• api.py: Added ListCourseEnrollmentsView with VIEW_ENROLLMENTS permission (HasAccessRule('staff')).
• api_urls.py: Registered the new list_course_enrollments URL pattern.
• serializer.py: Added EnrollmentListSerializer for request validation.

Shared features across both endpoints:

• Search filters by username, email, first_name, or last_name (case-insensitive)
• Pagination with configurable page_size (default: 20, max: 100)
• Response includes count, num_pages, and current_page metadata

User roles impacted: Course Staff, Course Instructors, Developers building against the instructor API.

Supporting information

• GitHub Issue: Enrollments API - Lists #37536
• Related frontend ticket: 6. Epic - Tab Content: Enrollments frontend-app-instruct#10

Testing instructions

List Course Enrollments

1. As a course staff/instructor user, POST /courses/{course_id}/instructor/api/list_course_enrollments with an empty body {}.
2. Verify the response includes course_id, enrollments (list of user objects), count, num_pages, and current_page.
3. Verify only active enrollments are included (inactive enrollments should be excluded).
4. Test search: send {"search": "partial_username"} and verify filtered results.
5. Test pagination: send {"page": 1, "page_size": 5} and verify correct page size and metadata.
6. Test invalid inputs: {"page": 0} and {"page_size": 0} should return 400.
7. Test permission: a non-staff user should receive 403.

Deadline

None

Other information

• No database migrations required.
• The ListCourseEnrollmentsView uses the VIEW_ENROLLMENTS permission (HasAccessRule('staff')) to allow course staff and instructors access, consistent with other enrollment-viewing endpoints.
• The enrollment list endpoint uses database-level filtering (Django ORM Q objects) for search, while the role members endpoint uses in-memory filtering since list_with_level returns a Python list.

[openedx-webhooks]

Thanks for the pull request, @brianjbuck-wgu!

This repository is currently maintained by @openedx/wg-maintenance-openedx-platform.

Once you've gone through the following steps feel free to tag them in a comment and let them know that your changes are ready for engineering review.

🔘 Get product approval

If you haven't already, check this list to see if your contribution needs to go through the product review process.

• If it does, you'll need to submit a product proposal for your contribution, and have it reviewed by the Product Working Group.
  • This process (including the steps you'll need to take) is documented here.
• If it doesn't, simply proceed with the next step.

🔘 Provide context

To help your reviewers and other members of the community understand the purpose and larger context of your changes, feel free to add as much of the following information to the PR description as you can:

• Dependencies

  This PR must be merged before / after / at the same time as ...

• Blockers

  This PR is waiting for OEP-1234 to be accepted.

• Timeline information

  This PR must be merged by XX date because ...

• Partner information

  This is for a course on edx.org.

• Supporting documentation
• Relevant Open edX discussion forum threads

🔘 Get a green build

If one or more checks are failing, continue working on your changes until this is no longer the case and your build turns green.

Details

---

Where can I find more information?

If you'd like to get more details on all aspects of the review process for open source pull requests (OSPRs), check out the following resources:

• Overview of Review Process for Community Contributions
• Pull Request Status Guide
• Making changes to your pull request

When can I expect my changes to be merged?

Our goal is to get community contributions seen and reviewed as efficiently as possible.

However, the amount of time that it takes to review and merge a PR can vary significantly based on factors such as:

• The size and impact of the changes that it introduces
• The need for product review
• Maintenance status of the parent repository

💡 As a result it may take up to several weeks or months to complete a review and merge your PR.

[Copilot]

Pull request overview

Adds a new list_course_enrollments endpoint and enhances the existing list_course_role_members endpoint with search and pagination support for the instructor dashboard MFE.

Changes:

• New ListCourseEnrollmentsView with DB-level search filtering and pagination for active course enrollments
• Enhanced ListCourseRoleMembersView with optional search, page, and page_size parameters (backward compatible)
• New serializers and comprehensive test coverage for both endpoints

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
lms/djangoapps/instructor/views/api.py	New ListCourseEnrollmentsView and search/pagination for ListCourseRoleMembersView
lms/djangoapps/instructor/views/api_urls.py	Registers the new list_course_enrollments URL
lms/djangoapps/instructor/views/serializer.py	New EnrollmentListSerializer and extended RoleNameSerializer with search/pagination fields
lms/djangoapps/instructor/tests/test_enrollment_list_api.py	Comprehensive tests for both endpoints
lms/djangoapps/instructor/tests/test_api.py	Updates existing tests to include new pagination metadata fields

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

[Copilot]

Bug: get_course_with_access is called with 'instructor' access level, but permission_name is set to permissions.VIEW_ENROLLMENTS which corresponds to HasAccessRule('staff'). This means course staff users will pass the permission check but then get a 404 from get_course_with_access since they don't have instructor-level access. This should use 'staff' instead of 'instructor' to be consistent with the permission, or match what the ListCourseRoleMembersView does (which uses EDIT_COURSE_ACCESS permission with 'instructor' access level).

Suggested change

	request.user, 'instructor', course_key, depth=None
	request.user, 'staff', course_key, depth=None

[diana-villalvazo-wgu]

Why are we using POST instead of GET to retrieve lists? 🤔

[diana-villalvazo-wgu]

i think we need to combine the endpoints, because on the new table we will need to know if user is beta tester or not, if we have that in separate endpoints will be an extra step to make it match, so can we add a boolean attribute just to know if the user is beta tester or not on the endpoint for enrollments list?

[diana-villalvazo-wgu]

I tested this, works, but i have one comment:

• I'm not getting anything on first name and last name, but on the fix can we get full_name instead?

[diana-villalvazo-wgu]

We will need a post endpoint for checking learner enrollment status, not sure if its planned for this PR or another one, basically i will just send the username or email and i should get if it is enrolled (active), inactive or never enrolled (unenrolled)

[diana-villalvazo-wgu]

Also i just saw on the requirements that for the list we should have this:

• The table is sorted alphabetically by Username 😅

[diana-villalvazo-wgu]

get for enrollments list works as expected 👍

[diana-villalvazo-wgu]

We will need a post endpoint for checking learner enrollment status, not sure if its planned for this PR or another one, basically i will just send the username or email and i should get if it is enrolled (active), inactive or never enrolled (unenrolled)

For this one i will reuse old endpoint 👍
/courses/{courseId}/instructor/api/get_student_enrollment_status

[brianjbuck-wgu]

We will need a post endpoint for checking learner enrollment status, not sure if its planned for this PR or another one, basically i will just send the username or email and i should get if it is enrolled (active), inactive or never enrolled (unenrolled)

For this one i will reuse old endpoint 👍 /courses/{courseId}/instructor/api/get_student_enrollment_status

@diana-villalvazo-wgu, yes, this is planned for the actions branch/PR

[diana-villalvazo-wgu]

I tested GET /api/instructor/v2/courses/${courseId}/enrollments and works as expected 👍 pending: filter by beta tester

[diana-villalvazo-wgu]

already tested filters, works as expected, maybe just update PR description and remove the role members endpoint not used as part of this PR

[brianjbuck-wgu]

@diana-villalvazo-wgu, I updated the description :)

[diana-villalvazo-wgu]

Approved and tested on branch openedx/frontend-app-instruct#139