enrollments_api_controller.rb

#
# Copyright (C) 2011 - present 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_account_id": {
#             "description": "The SIS Account 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"
#           },
#           "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"
#           },
#           "sis_user_id": {
#             "description": "The SIS User 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"
#           },
#           "role_id": {
#             "description": "The id of the enrollment role.",
#             "example": 1,
#             "type": "integer"
#           },
#           "created_at": {
#             "description": "The created time of the enrollment, in ISO8601 format.",
#             "example": "2012-04-18T23:08:51Z",
#             "type": "datetime"
#           },
#           "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 containing the grades associated with this enrollment.",
#             "$ref": "Grade"
#           },
#           "computed_current_score": {
#             "description": "optional: The student's score in the course, ignoring ungraded assignments. (applies only to student enrollments, and only available in course endpoints)",
#             "example": 90.25,
#             "type": "number"
#           },
#           "computed_final_score": {
#             "description": "optional: The student's score in the course including ungraded assignments with a score of 0. (applies only to student enrollments, and only available in course endpoints)",
#             "example": 80.67,
#             "type": "number"
#           },
#           "computed_current_grade": {
#             "description": "optional: The letter grade equivalent of computed_current_score, if available. (applies only to student enrollments, and only available in course endpoints)",
#             "example": "A-",
#             "type": "string"
#           },
#           "computed_final_grade": {
#             "description": "optional: The letter grade equivalent of computed_final_score, if available. (applies only to student enrollments, and only available in course endpoints)",
#             "example": "B-",
#             "type": "string"
#           },
#           "has_grading_periods": {
#             "description": "optional: Indicates whether the course the enrollment belongs to has grading periods set up. (applies only to student enrollments, and only available in course endpoints)",
#             "example": true,
#             "type": "boolean"
#           },
#           "totals_for_all_grading_periods_option": {
#             "description": "optional: Indicates whether the course the enrollment belongs to has the Display Totals for 'All Grading Periods' feature enabled. (applies only to student enrollments, and only available in course endpoints)",
#             "example": true,
#             "type": "boolean"
#           },
#           "current_grading_period_title": {
#             "description": "optional: The name of the currently active grading period, if one exists. If the course the enrollment belongs to does not have grading periods, or if no currently active grading period exists, the value will be null. (applies only to student enrollments, and only available in course endpoints)",
#             "example": "Fall Grading Period",
#             "type": "string"
#           },
#           "current_grading_period_id": {
#             "description": "optional: The id of the currently active grading period, if one exists. If the course the enrollment belongs to does not have grading periods, or if no currently active grading period exists, the value will be null. (applies only to student enrollments, and only available in course endpoints)",
#             "example": 5,
#             "type": "integer"
#           },
#           "current_period_computed_current_score": {
#             "description": "optional: The student's score in the course for the current grading period, ignoring ungraded assignments. If the course the enrollment belongs to does not have grading periods, or if no currently active grading period exists, the value will be null. (applies only to student enrollments, and only available in course endpoints)",
#             "example": 95.80,
#             "type": "number"
#           },
#           "current_period_computed_final_score": {
#             "description": "optional: The student's score in the course for the current grading period, including ungraded assignments with a score of 0. If the course the enrollment belongs to does not have grading periods, or if no currently active grading period exists, the value will be null. (applies only to student enrollments, and only available in course endpoints)",
#             "example": 85.25,
#             "type": "number"
#           },
#           "current_period_computed_current_grade": {
#             "description": "optional: The letter grade equivalent of current_period_computed_current_score, if available. If the course the enrollment belongs to does not have grading periods, or if no currently active grading period exists, the value will be null. (applies only to student enrollments, and only available in course endpoints)",
#             "example": "A",
#             "type": "string"
#           },
#           "current_period_computed_final_grade": {
#             "description": "optional: The letter grade equivalent of current_period_computed_final_score, if available. If the course the enrollment belongs to does not have grading periods, or if no currently active grading period exists, the value will be null. (applies only to student enrollments, and only available in course endpoints)",
#             "example": "B",
#             "type": "string"
#           }
#         }
#       }
#
class EnrollmentsApiController < ApplicationController
  before_action :get_course_from_section, :require_context
  before_action :require_user

  @@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.',
    :insufficient_sis_permissions      => 'Insufficient permissions to filter by SIS fields'
  }

  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 include[] [String, "avatar_url"|"group_ids"|"locked"|"observed_users"|"can_be_removed"]
  #   Array of additional information to include on the enrollment or user records.
  #   "avatar_url" and "group_ids" will be returned on the user record.
  #
  # @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.
  #
  # @argument sis_account_id[] [String]
  #   Returns only enrollments for the specified SIS account ID(s). Does not
  #   look into subaccounts. May pass in array or string.
  #
  # @argument sis_course_id[] [String]
  #   Returns only enrollments matching the specified SIS course ID(s).
  #   May pass in array or string.
  #
  # @argument sis_section_id[] [String]
  #   Returns only section enrollments matching the specified SIS section ID(s).
  #   May pass in array or string.
  #
  # @argument sis_user_id[] [String]
  #   Returns only enrollments for the specified SIS user ID(s). May pass in
  #   array or string.
  #
  # @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")}, enrollments.id")

    has_courses = (CANVAS_RAILS4_2 ? enrollments.where_values : enrollments.where_clause.instance_variable_get(:@predicates)).
      any? { |cond| cond.is_a?(String) && cond =~ /courses\./ }
    enrollments = enrollments.joins(:course) if has_courses
    enrollments = enrollments.shard(@shard_scope) if @shard_scope

    sis_context = @context.is_a?(Course) ? @context : @domain_root_account
    unless check_sis_permissions(sis_context)
      render_create_errors([@@errors[:insufficient_sis_permissions]])
      return false
    end

    if params[:sis_user_id].present?
      pseudonyms = @domain_root_account.pseudonyms.where(sis_user_id: params[:sis_user_id])
      enrollments = enrollments.where(user_id: pseudonyms.pluck(:user_id))
    end

    if params[:sis_section_id].present?
      sections = @domain_root_account.course_sections.where(sis_source_id: params[:sis_section_id])
      enrollments = enrollments.where(course_section_id: sections.pluck(:id))
    end

    if params[:sis_account_id].present?
      accounts = @domain_root_account.all_accounts.where(sis_source_id: params[:sis_account_id])
      courses = @domain_root_account.all_courses.where(account_id: accounts.pluck(:id))
      enrollments = enrollments.where(course_id: courses.pluck(:id))
    end

    if params[:sis_course_id].present?
      courses = @domain_root_account.all_courses.where(sis_source_id: params[:sis_course_id])
      enrollments = enrollments.where(course_id: courses.pluck(:id))
    end

    if params[:grading_period_id].present?
      if @context.is_a? User
        grading_period = @context.courses.lazy.map do |course|
          GradingPeriod.for(course).find_by(id: params[:grading_period_id])
        end.detect(&:present?)
      else
        grading_period = GradingPeriod.for(@context).find_by(id: params[:grading_period_id])
      end

      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.preload(enrollments, [:user, :course, :course_section])

    include_group_ids = Array(params[:include]).include?("group_ids")
    includes = [:user] + Array(params[:include])
    user_json_preloads(enrollments.map(&:user), false, {group_memberships: include_group_ids})

    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
    enrollment = @context.all_enrollments.find(params[:id])
    if enrollment.user_id == @current_user.id || authorized_action(@context, @current_user, :read_roster)
      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"|"inactive"]
  #   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.'.
  #
  #   If set to 'inactive', student will be listed in the course roster for
  #   teachers, but will not be able to participate in the course until
  #   their enrollment is activated.
  #
  # @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 set, the enrollment will only allow the user to see and interact with
  #   users enrolled in the section given by course_section_id.
  #   * For teachers and TAs, this includes grading privileges.
  #   * Section-limited students will not see any users (including teachers
  #     and TAs) not enrolled in their sections.
  #   * Users may have other enrollments that grant privileges to
  #     multiple sections in the same course.
  #
  # @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.
  #
  # @argument enrollment[associated_user_id] [Integer]
  #   For an observer enrollment, the ID of a student to observe. The
  #   caller must have +manage_students+ permission in the course.
  #   This is a one-off operation; to automatically observe all a
  #   student's enrollments (for example, as a parent), please use
  #   the {api:UserObserveesController#create User Observees API}.
  #
  # @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

    params[:enrollment][:limit_privileges_to_course_section] = value_to_boolean(params[:enrollment][:limit_privileges_to_course_section]) if params[:enrollment].has_key?(:limit_privileges_to_course_section)
    params[:enrollment].slice!(:enrollment_state, :section, :limit_privileges_to_course_section, :associated_user_id, :role, :start_at, :end_at, :self_enrolled, :no_notify)

    @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 create_self_enrollment
    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, deactivate, or delete an enrollment
  # Conclude, deactivate, or delete an enrollment. If the +task+ argument isn't given, the enrollment
  # will be concluded.
  #
  # @argument task [String, "conclude"|"delete"|"inactivate"|"deactivate"]
  #   The action to take on the enrollment.
  #   When inactive, a user will still appear in the course roster to admins, but be unable to participate.
  #   ("inactivate" and "deactivate" are equivalent tasks)
  #
  # @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])
    permission =
      case params[:task]
      when 'conclude'
        :can_be_concluded_by
      when 'delete', 'deactivate', 'inactivate'
        :can_be_deleted_by
      else
        :can_be_concluded_by
      end

    action =
      case params[:task]
      when 'conclude'
        :conclude
      when 'delete'
        :destroy
      when 'deactivate', 'inactivate'
        :deactivate
      else
        :conclude
      end

    unless @enrollment.send(permission, @current_user, @context, session)
      return render_unauthorized_action
    end

    if @enrollment.send(action)
      render :json => enrollment_json(@enrollment, @current_user, session)
    else
      render :json => @enrollment.errors, :status => :bad_request
    end
  end

  # @API Re-activate an enrollment
  # Activates an inactive enrollment
  #
  # @example_request
  #   curl https://<canvas>/api/v1/courses/:course_id/enrollments/:enrollment_id/reactivate \
  #     -X PUT
  #
  # @returns Enrollment
  def reactivate
    @enrollment = @context.enrollments.find(params[:id])

    unless @enrollment.send(:can_be_deleted_by, @current_user, @context, session)
      return render_unauthorized_action
    end


    unless @enrollment.workflow_state == 'inactive'
      return render(:json => {:error => "enrollment not inactive"}, :status => :bad_request)
    end

    if @enrollment.reactivate
      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.apply_enrollment_visibility(@context.all_enrollments, @current_user).where(enrollment_index_conditions)

      unless params[:state].present?
        include_inactive = @context.grants_right?(@current_user, session, :read_as_admin)
        scope = include_inactive ? scope.all_active_or_pending : 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
      is_approved_parent = user.grants_right?(@current_user, :read_as_parent)
      # 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 is_approved_parent || 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

  def check_sis_permissions(sis_context)
    sis_filters = %w(sis_account_id sis_course_id sis_section_id sis_user_id)
    if (params.keys & sis_filters).present?
      unless sis_context.grants_any_right?(@current_user, :read_sis, :manage_sis)
        return false
      end
    end

    true
  end

  def render_create_errors(errors)
    render json: {message: errors.join(', ')}, status: 403
  end
end