Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Branch: master
Fetching contributors…

Cannot retrieve contributors at this time

601 lines (554 sloc) 24.344 kB
#
# Copyright (C) 2011 - 2014 Instructure, Inc.
#
# This file is part of Canvas.
#
# Canvas is free software: you can redistribute it and/or modify it under
# the terms of the GNU Affero General Public License as published by the Free
# Software Foundation, version 3 of the License.
#
# Canvas is distributed in the hope that it will be useful, but WITHOUT ANY
# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
# A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
# details.
#
# You should have received a copy of the GNU Affero General Public License along
# with this program. If not, see <http://www.gnu.org/licenses/>.
#
# @API Enrollments
#
# API for creating and viewing course enrollments
#
# @model Grade
# {
# "id": "Grade",
# "description": "",
# "properties": {
# "html_url": {
# "description": "The URL to the Canvas web UI page for the user's grades, if this is a student enrollment.",
# "example": "",
# "type": "string"
# },
# "current_grade": {
# "description": "The user's current grade in the class. Only included if user has permissions to view this grade.",
# "example": "",
# "type": "string"
# },
# "final_grade": {
# "description": "The user's final grade for the class. Only included if user has permissions to view this grade.",
# "example": "",
# "type": "string"
# },
# "current_score": {
# "description": "The user's current score in the class. Only included if user has permissions to view this score.",
# "example": "",
# "type": "string"
# },
# "final_score": {
# "description": "The user's final score for the class. Only included if user has permissions to view this score.",
# "example": "",
# "type": "string"
# }
# }
# }
#
# @model Enrollment
# {
# "id": "Enrollment",
# "description": "",
# "properties": {
# "id": {
# "description": "The ID of the enrollment.",
# "example": 1,
# "type": "integer"
# },
# "course_id": {
# "description": "The unique id of the course.",
# "example": 1,
# "type": "integer"
# },
# "sis_course_id": {
# "description": "The SIS Course ID in which the enrollment is associated. Only displayed if present. This field is only included if the user has permission to view SIS information.",
# "example": "SHEL93921",
# "type": "string"
# },
# "course_integration_id": {
# "description": "The Course Integration ID in which the enrollment is associated. This field is only included if the user has permission to view SIS information.",
# "example": "SHEL93921",
# "type": "string"
# },
# "course_section_id": {
# "description": "The unique id of the user's section.",
# "example": 1,
# "type": "integer"
# },
# "section_integration_id": {
# "description": "The Section Integration ID in which the enrollment is associated. This field is only included if the user has permission to view SIS information.",
# "example": "SHEL93921",
# "type": "string"
# },
# "sis_section_id": {
# "description": "The SIS Section ID in which the enrollment is associated. Only displayed if present. This field is only included if the user has permission to view SIS information.",
# "example": "SHEL93921",
# "type": "string"
# },
# "enrollment_state": {
# "description": "The state of the user's enrollment in the course.",
# "example": "active",
# "type": "string"
# },
# "limit_privileges_to_course_section": {
# "description": "User can only access his or her own course section.",
# "example": true,
# "type": "boolean"
# },
# "sis_import_id": {
# "description": "The unique identifier for the SIS import. This field is only included if the user has permission to manage SIS information.",
# "example": 83,
# "type": "integer"
# },
# "root_account_id": {
# "description": "The unique id of the user's account.",
# "example": 1,
# "type": "integer"
# },
# "type": {
# "description": "The enrollment type. One of 'StudentEnrollment', 'TeacherEnrollment', 'TaEnrollment', 'DesignerEnrollment', 'ObserverEnrollment'.",
# "example": "StudentEnrollment",
# "type": "string"
# },
# "user_id": {
# "description": "The unique id of the user.",
# "example": 1,
# "type": "integer"
# },
# "associated_user_id": {
# "description": "The unique id of the associated user. Will be null unless type is ObserverEnrollment.",
# "example": null,
# "type": "integer"
# },
# "role": {
# "description": "The enrollment role, for course-level permissions. This field will match `type` if the enrollment role has not been customized.",
# "example": "StudentEnrollment",
# "type": "string"
# },
# "updated_at": {
# "description": "The updated time of the enrollment, in ISO8601 format.",
# "example": "2012-04-18T23:08:51Z",
# "type": "datetime"
# },
# "start_at": {
# "description": "The start time of the enrollment, in ISO8601 format.",
# "example": "2012-04-18T23:08:51Z",
# "type": "datetime"
# },
# "end_at": {
# "description": "The end time of the enrollment, in ISO8601 format.",
# "example": "2012-04-18T23:08:51Z",
# "type": "datetime"
# },
# "last_activity_at": {
# "description": "The last activity time of the user for the enrollment, in ISO8601 format.",
# "example": "2012-04-18T23:08:51Z",
# "type": "datetime"
# },
# "total_activity_time": {
# "description": "The total activity time of the user for the enrollment, in seconds.",
# "example": 260,
# "type": "integer"
# },
# "html_url": {
# "description": "The URL to the Canvas web UI page for this course enrollment.",
# "example": "https://...",
# "type": "string"
# },
# "grades": {
# "description": "The URL to the Canvas web UI page the grades associated with this enrollment.",
# "$ref": "Grade"
# },
# "user": {
# "description": "A description of the user.",
# "type": "User"
# }
# }
# }
#
class EnrollmentsApiController < ApplicationController
before_filter :get_course_from_section, :require_context
@@errors = {
:missing_parameters => 'No parameters given',
:missing_user_id => "Can't create an enrollment without a user. Include enrollment[user_id] to create an enrollment",
:bad_type => 'Invalid type',
:bad_role => 'Invalid role',
:inactive_role => 'Cannot create an enrollment with this role because it is inactive.',
:base_type_mismatch => 'The specified type must match the base type for the role',
:concluded_course => 'Can\'t add an enrollment to a concluded course.',
:multiple_grading_periods_disabled => 'Multiple Grading Periods feature is disabled. Cannot filter by grading_period_id with this feature disabled'
}
include Api::V1::User
# @API List enrollments
# Depending on the URL given, return either (1) all of the enrollments in
# a course, (2) all of the enrollments in a section or (3) all of a user's
# enrollments. This includes student, teacher, TA, and observer enrollments.
#
# If a user has multiple enrollments in a context (e.g. as a teacher
# and a student or in multiple course sections), each enrollment will be
# listed separately.
#
# note: Currently, only an admin user can return other users' enrollments. A
# user can, however, return his/her own enrollments.
#
# @argument type[] [String]
# A list of enrollment types to return. Accepted values are
# 'StudentEnrollment', 'TeacherEnrollment', 'TaEnrollment',
# 'DesignerEnrollment', and 'ObserverEnrollment.' If omitted, all enrollment
# types are returned. This argument is ignored if `role` is given.
#
# @argument role[] [String]
# A list of enrollment roles to return. Accepted values include course-level
# roles created by the {api:RoleOverridesController#add_role Add Role API}
# as well as the base enrollment types accepted by the `type` argument above.
#
# @argument state[] [String, "active"|"invited"|"creation_pending"|"deleted"|"rejected"|"completed"|"inactive"]
# Filter by enrollment state. If omitted, 'active' and 'invited' enrollments
# are returned. When querying a user's enrollments (either via user_id
# argument or via user enrollments endpoint), the following additional
# synthetic states are supported: "current_and_invited"|"current_and_future"|"current_and_concluded"
#
# @argument user_id [String]
# Filter by user_id (only valid for course or section enrollment
# queries). If set to the current user's id, this is a way to
# determine if the user has any enrollments in the course or section,
# independent of whether the user has permission to view other people
# on the roster.
#
# @argument grading_period_id [Integer]
# Return grades for the given grading_period. If this parameter is not
# specified, the returned grades will be for the whole course.
#
# @returns [Enrollment]
def index
endpoint_scope = (@context.is_a?(Course) ? (@section.present? ? "section" : "course") : "user")
return unless enrollments = @context.is_a?(Course) ?
course_index_enrollments :
user_index_enrollments
enrollments = enrollments.joins(:user).select("enrollments.*").
order("enrollments.type, #{User.sortable_name_order_by_clause("users")}")
has_courses = enrollments.where_values.any? { |cond| cond.is_a?(String) && cond =~ /courses\./ }
enrollments = enrollments.joins(:course) if has_courses
enrollments = enrollments.shard(@shard_scope) if @shard_scope
if params[:grading_period_id].present?
if !multiple_grading_periods?
render_create_errors([@@errors[:multiple_grading_periods_disabled]])
return false
end
if @context.is_a? User
render(
json: {message: "grading_period_id can't be specified for users"},
status: 403
)
return false
end
grading_period = GradingPeriod.context_find(@context, params[:grading_period_id])
unless grading_period
render(:json => {error: "invalid grading_period_id"}, :status => :bad_request)
return
end
end
enrollments = Api.paginate(
enrollments,
self, send("api_v1_#{endpoint_scope}_enrollments_url"))
ActiveRecord::Associations::Preloader.new(enrollments, [:user, :course, :course_section]).run
includes = [:user] + Array(params[:include])
user_json_preloads(enrollments.map(&:user))
render :json => enrollments.map { |e|
enrollment_json(e, @current_user, session, includes,
grading_period: grading_period)
}
end
# @API Enrollment by ID
# Get an Enrollment object by Enrollment ID
#
# @argument id [Required, Integer]
# The ID of the enrollment object
# @returns Enrollment
def show
render_unauthorized_action and return false unless @current_user
enrollment = Enrollment.find(params[:id])
if enrollment.user_id == @current_user.id || enrollment.root_account == @context && authorized_action(@context, @current_user, [:read_roster])
#render enrollment object if requesting user is the current_user or user is authorized to read enrollment.
render :json => enrollment_json(enrollment, @current_user, session)
end
end
# @API Enroll a user
# Create a new user enrollment for a course or section.
#
# @argument enrollment[user_id] [Required, String]
# The ID of the user to be enrolled in the course.
#
# @argument enrollment[type] [Required, String, "StudentEnrollment"|"TeacherEnrollment"|"TaEnrollment"|"ObserverEnrollment"|"DesignerEnrollment"]
# Enroll the user as a student, teacher, TA, observer, or designer. If no
# value is given, the type will be inferred by enrollment[role] if supplied,
# otherwise 'StudentEnrollment' will be used.
#
# @argument enrollment[role] [Deprecated, String]
# Assigns a custom course-level role to the user.
#
# @argument enrollment[role_id] [Integer]
# Assigns a custom course-level role to the user.
#
# @argument enrollment[enrollment_state] [String, "active"|"invited"]
# If set to 'active,' student will be immediately enrolled in the course.
# Otherwise they will be required to accept a course invitation. Default is
# 'invited.'
#
# @argument enrollment[course_section_id] [Integer]
# The ID of the course section to enroll the student in. If the
# section-specific URL is used, this argument is redundant and will be
# ignored.
#
# @argument enrollment[limit_privileges_to_course_section] [Boolean]
# If a teacher or TA enrollment, teacher/TA will be restricted to the
# section given by course_section_id.
#
# @argument enrollment[notify] [Boolean]
# If true, a notification will be sent to the enrolled user.
# Notifications are not sent by default.
#
# @argument enrollment[self_enrollment_code] [String]
# If the current user is not allowed to manage enrollments in this
# course, but the course allows self-enrollment, the user can self-
# enroll as a student in the default section by passing in a valid
# code. When self-enrolling, the user_id must be 'self'. The
# enrollment_state will be set to 'active' and all other arguments
# will be ignored.
#
# @argument enrollment[self_enrolled] [Boolean]
# If true, marks the enrollment as a self-enrollment, which gives
# students the ability to drop the course if desired. Defaults to false.
#
# @example_request
# curl https://<canvas>/api/v1/courses/:course_id/enrollments \
# -X POST \
# -F 'enrollment[user_id]=1' \
# -F 'enrollment[type]=StudentEnrollment' \
# -F 'enrollment[enrollment_state]=active' \
# -F 'enrollment[course_section_id]=1' \
# -F 'enrollment[limit_privileges_to_course_section]=true' \
# -F 'enrollment[notify]=false'
#
# @example_request
# curl https://<canvas>/api/v1/courses/:course_id/enrollments \
# -X POST \
# -F 'enrollment[user_id]=2' \
# -F 'enrollment[type]=StudentEnrollment'
#
# @returns Enrollment
def create
# error handling
errors = []
if params[:enrollment].blank?
errors << @@errors[:missing_parameters] if params[:enrollment].blank?
else
return create_self_enrollment if params[:enrollment][:self_enrollment_code]
type = params[:enrollment].delete(:type)
if role_id = params[:enrollment].delete(:role_id)
role = @context.account.get_role_by_id(role_id)
elsif role_name = params[:enrollment].delete(:role)
role = @context.account.get_course_role_by_name(role_name)
else
type = "StudentEnrollment" if type.blank?
role = Role.get_built_in_role(type)
if role.nil? || !role.course_role?
errors << @@errors[:bad_type]
end
end
if role && role.course_role? && !role.deleted?
type = role.base_role_type if type.blank?
if role.inactive?
errors << @@errors[:inactive_role]
elsif type != role.base_role_type
errors << @@errors[:base_type_mismatch]
else
params[:enrollment][:role] = role
end
elsif errors.empty?
errors << @@errors[:bad_role]
end
errors << @@errors[:missing_user_id] unless params[:enrollment][:user_id].present?
end
return render_create_errors(errors) if errors.present?
# create enrollment
params[:enrollment][:no_notify] = true unless value_to_boolean(params[:enrollment][:notify])
unless @current_user.can_create_enrollment_for?(@context, session, type)
render_unauthorized_action && return
end
params[:enrollment][:course_section_id] = @section.id if @section.present?
if params[:enrollment][:course_section_id].present?
@section = @context.course_sections.active.find params[:enrollment].delete(:course_section_id)
params[:enrollment][:section] = @section
end
api_user_id = params[:enrollment].delete(:user_id)
user = api_find(User, api_user_id)
raise(ActiveRecord::RecordNotFound, "Couldn't find User with API id '#{api_user_id}'") unless user.can_be_enrolled_in_course?(@context)
if @context.concluded?
# allow moving users already in the course to open sections
unless @section && user.enrollments.where(course_id: @context).exists? && !@section.concluded?
return render_create_errors([@@errors[:concluded_course]])
end
end
@enrollment = @context.enroll_user(user, type, params[:enrollment].merge(:allow_multiple_enrollments => true))
@enrollment.valid? ?
render(:json => enrollment_json(@enrollment, @current_user, session)) :
render(:json => @enrollment.errors, :status => :bad_request)
end
def render_create_errors(errors)
render json: {message: errors.join(', ')}, status: 403
end
def create_self_enrollment
require_user
options = params[:enrollment]
code = options[:self_enrollment_code]
# we don't just do a straight-up comparison of the code, since
# plugins can override Account#self_enrollment_course_for to allow
# for synthetic ones
errors = []
if @context != @context.root_account.self_enrollment_course_for(code)
errors << "enrollment[self_enrollment_code] is invalid"
end
if options[:user_id] != 'self'
errors << "enrollment[user_id] must be 'self' when self-enrolling"
end
return render_create_errors(errors) if errors.present?
@current_user.validation_root_account = @domain_root_account
@current_user.require_self_enrollment_code = true
@current_user.self_enrollment_code = code
if @current_user.save
render(json: enrollment_json(@current_user.self_enrollment, @current_user, session))
else
render(json: {user: @current_user.errors}, status: :bad_request)
end
end
# @API Conclude an enrollment
# Delete or conclude an enrollment.
#
# @argument task [String, "conclude"|"delete"]
# The action to take on the enrollment.
#
# @example_request
# curl https://<canvas>/api/v1/courses/:course_id/enrollments/:enrollment_id \
# -X DELETE \
# -F 'task=conclude'
#
# @returns Enrollment
def destroy
@enrollment = @context.enrollments.find(params[:id])
task = %w{conclude delete}.include?(params[:task]) ? params[:task] : 'conclude'
unless @enrollment.send("can_be_#{task}d_by", @current_user, @context, session)
return render_unauthorized_action
end
task = 'destroy' if task == 'delete'
if @enrollment.send(task)
render :json => enrollment_json(@enrollment, @current_user, session)
else
render :json => @enrollment.errors, :status => :bad_request
end
end
protected
# Internal: Collect course enrollments that @current_user has permissions to
# read.
#
# Returns an ActiveRecord scope of enrollments on success, false on failure.
def course_index_enrollments
if params[:user_id]
# if you pass in your own id, you can see if you are enrolled in the
# course, regardless of whether you have read_roster
scope = user_index_enrollments
return scope && scope.where(course_id: @context.id)
end
if authorized_action(@context, @current_user, [:read_roster, :view_all_grades, :manage_grades])
scope = @context.enrollments_visible_to(@current_user, :type => :all, :include_priors => true).where(enrollment_index_conditions)
unless params[:state].present?
scope = scope.active_or_pending
end
scope
else
false
end
end
# Internal: Collect user enrollments that @current_user has permissions to
# read.
#
# Returns an ActiveRecord scope of enrollments on success, false on failure.
def user_index_enrollments
user = api_find(User, params[:user_id])
if user == @current_user
# if user is requesting for themselves, just return all of their
# enrollments without any extra checking.
if params[:state].present?
enrollments = user.enrollments.where(enrollment_index_conditions(true))
else
enrollments = user.enrollments.current_and_invited.where(enrollment_index_conditions)
end
else
# otherwise check for read_roster rights on all of the requested
# user's accounts
approved_accounts = user.associated_root_accounts.inject([]) do |accounts, ra|
accounts << ra.id if ra.grants_right?(@current_user, session, :read_roster)
accounts
end
# if there aren't any ids in approved_accounts, then the user doesn't have
# permissions.
render_unauthorized_action and return false if approved_accounts.empty?
enrollments = user.enrollments.where(enrollment_index_conditions).
where(root_account_id: approved_accounts)
# by default, return active and invited courses. don't use the existing
# current_and_invited_enrollments scope because it won't return enrollments
# on unpublished courses.
enrollments = enrollments.where(workflow_state: %w{active invited}) unless params[:state].present?
end
@shard_scope = user
enrollments
end
# Internal: Collect type, section, state, and role info from params and format them
# for use in a request for the requester's own enrollments.
# index is :course or :user
#
# Returns [ sql fragment string, replacement hash ]
def enrollment_index_conditions(use_course_state = false)
type, state, role_names, role_ids = params.values_at(:type, :state, :role, :role_id)
clauses = []
replacements = {}
if !role_ids.present? && role_names.present?
role_ids = Array(role_names).map{|name| @context.account.get_course_role_by_name(name).id}
end
if role_ids.present?
role_ids = Array(role_ids).map(&:to_i)
condition = 'enrollments.role_id IN (:role_ids)'
replacements[:role_ids] = role_ids
built_in_roles = role_ids.map{|r_id| Role.built_in_roles_by_id[r_id]}.compact
if built_in_roles.present?
condition = "(#{condition} OR (enrollments.role_id IS NULL AND enrollments.type IN (:built_in_role_types)))"
replacements[:built_in_role_types] = built_in_roles.map(&:name)
end
clauses << condition
elsif type.present?
clauses << 'enrollments.type IN (:type)'
replacements[:type] = Array(type)
end
if state.present?
if use_course_state
conditions = state.map{ |s| Enrollment::QueryBuilder.new(s.to_sym).conditions }.compact
clauses << "(#{conditions.join(' OR ')})"
else
clauses << 'enrollments.workflow_state IN (:workflow_state)'
replacements[:workflow_state] = Array(state)
end
end
if @section.present?
clauses << 'enrollments.course_section_id = :course_section_id'
replacements[:course_section_id] = @section.id
end
[ clauses.join(' AND '), replacements ]
end
end
Jump to Line
Something went wrong with that request. Please try again.