feat(invitations): multi-language CSV parsing, locale templates, and external ID conflict resolution

app/controllers/course/user_invitations_controller.rb

@@ -15,8 +15,20 @@ def index
 
   def create
     result = invite
-    if result
+    case result
+    when Array
       create_invitation_success(result)
+    when :pending_conflict
+      respond_to do |format|
+        format.json do
+          render partial: 'pending_external_id_data',
+                 locals: {
+                   pending_invitation_updates: @pending_conflict.pending_invitation_updates,
+                   pending_course_user_updates: @pending_conflict.pending_course_user_updates
+                 },
+                 status: :ok
+        end
+      end
     else
       propagate_errors
       errors = current_course.errors[:base]
@@ -116,14 +128,25 @@ def invite_by_file?
     invitation_params.is_a?(Tempfile)
   end
 
+  VALID_EXTERNAL_ID_RESOLUTIONS = %w[keep_existing replace_all].freeze
+  private_constant :VALID_EXTERNAL_ID_RESOLUTIONS
+
   # Invites the users via the service object.
   #
-  # @return [Boolean] True if the invitation was successful.
+  # @return [Array] On success.
+  # @return [Symbol] :pending_conflict when external ID updates require resolution.
+  # @return [Boolean] false on failure.
   def invite
-    invitation_service.invite(invitation_params)
+    resolution = params[:external_id_resolution]
+    resolution = nil unless VALID_EXTERNAL_ID_RESOLUTIONS.include?(resolution)
+    invitation_service.invite(invitation_params,
+                              external_id_resolution: resolution)
   rescue CSV::MalformedCSVError => e
     current_course.errors.add(:base, e.message)
     false
+  rescue Course::UserInvitationService::PendingExternalIdUpdates => e
+    @pending_conflict = e
+    :pending_conflict
   end
 
   # Creates a user invitation service object for this object.
@@ -296,7 +319,8 @@ def create_invitation_success(result)
       format.json do
         render json: {
           newInvitations: result[0].length,
-          invitationResult: parse_invitation_result(*result)
+          invitationResult: parse_invitation_result(*result),
+          blankHeaderWarning: invitation_service.blank_header_warning
         }, status: :ok
       end
     end

app/services/concerns/course/user_invitation_service/parse_invitation_concern.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 require 'csv'
+require 'set'
 
 # This concern includes methods required to parse the invitations data.
 # This can either be from a form, or a CSV file.
@@ -9,6 +10,8 @@ module Course::UserInvitationService::ParseInvitationConcern
   extend ActiveSupport::Autoload
 
   TRUE_VALUES = ['t', 'true', 'y', 'yes'].freeze
+  SUPPORTED_LOCALES = %i[en zh ko].freeze
+  CANONICAL_COLUMNS = %i[name email external_id role phantom personal_timeline].freeze
 
   private
 
@@ -124,28 +127,25 @@ def parse_from_form(users)
   # @raise [CSV::MalformedCSVError] When the file provided is invalid, eg. UTF-16 encoding.
   def parse_from_file(file)
     row_num = 0
+    header_map = nil
+    blank_header_indices = []
+    @blank_header_warning = false
     [].tap do |invites|
       CSV.foreach(file, encoding: 'utf-8').with_index(1) do |row, row_number|
         row_num = row_number
-        row[0] = remove_utf8_byte_order_mark(row[0]) if row_number == 1
+        row[0] = remove_utf8_byte_order_mark(row[0]) if row_number == 1 && row[0]
         row = strip_row(row)
-        # Ignore first row if it's a header row.
-        next if row_number == 1 && header_row?(row)
-
-        invite = parse_file_row(row)
+        if row_number == 1
+          header_map, blank_header_indices = build_header_map!(row)
+          next
+        end
+        @blank_header_warning ||= blank_header_indices.any? { |idx| row[idx].present? }
+        invite = parse_file_row(row, header_map)
         invites << invite if invite
       end
     end
   rescue StandardError => e
-    raise CSV::MalformedCSVError.new(e, row_num), e.message
-  end
-
-  # Returns a boolean to determine whether the row is a header row.
-  #
-  # @param[Array] row Array read from CSV file.
-  # @return [Boolean] Whether the row is a header row
-  def header_row?(row)
-    row[0].casecmp('Name') == 0 && row[1].casecmp('Email') == 0
+    raise CSV::MalformedCSVError.new(e.message, row_num), e.message
   end
 
   # Strips a row of whitespaces.
@@ -156,32 +156,85 @@ def strip_row(row)
     row.map { |item| item&.strip }
   end
 
+  def header_alias_map
+    @header_alias_map ||= SUPPORTED_LOCALES.each_with_object({}) do |locale, map|
+      CANONICAL_COLUMNS.each do |col|
+        term = I18n.t("csv.course_user_invitations.headers.#{col}", locale: locale)
+        map[normalize_header(term)] = col
+      end
+    end
+  end
+
+  def normalize_header(value)
+    value&.strip&.downcase&.gsub(/[\s_\-]+/, '')
+  end
+
+  def build_header_map!(row)
+    resolved = {}
+    blank_indices = []
+    row.each_with_index do |cell, idx|
+      if cell.blank?
+        blank_indices << idx
+        next
+      end
+
+      canonical = header_alias_map[normalize_header(cell)]
+      raise_non_canonical_header_error!(cell) unless canonical
+      raise_duplicate_header_error!(canonical) if resolved.key?(canonical)
+
+      resolved[canonical] = idx
+    end
+
+    validate_required_headers!(resolved)
+    [resolved, blank_indices]
+  end
+
+  def raise_non_canonical_header_error!(cell)
+    accepted = CANONICAL_COLUMNS.map { |col| I18n.t("csv.course_user_invitations.headers.#{col}") }.join(', ')
+    raise I18n.t('errors.course.user_invitations.invalid_headers', header: cell, accepted: accepted)
+  end
+
+  def raise_duplicate_header_error!(canonical)
+    raise I18n.t('errors.course.user_invitations.duplicate_headers',
+                 column: I18n.t("csv.course_user_invitations.headers.#{canonical}"))
+  end
+
+  def validate_required_headers!(resolved)
+    return if resolved.key?(:name) && resolved.key?(:email)
+
+    raise I18n.t('errors.course.user_invitations.missing_required_headers')
+  end
+
   # Parses the given CSV row (array) and returns attributes for a user invitation.
+  #   - Columns are resolved by position via +header_map+, not by fixed order.
   #   - Sets the name as the given email if a name was not provided.
   #
-  # @param [Array] row Array with 3 parameters: name, email and role respectively.
+  # @param [Array] row The row's cells as read from the CSV file.
+  # @param [Hash{Symbol=>Integer}] header_map Maps each resolved canonical column
+  #   (a subset of +CANONICAL_COLUMNS+) to its index in +row+. Only +:name+ and
+  #   +:email+ are guaranteed present; optional columns are absent when not in the file.
   # @return [Hash] The parsed invitation attributes given the row.
-  def parse_file_row(row)
-    return nil if row[1].blank?
+  def parse_file_row(row, header_map)
+    email = row[header_map[:email]]
+    return nil if email.blank?
 
-    if !@current_course.show_personalized_timeline_features? && row.length > 5
-      raise I18n.t('errors.course.user_invitations.timeline_template_mismatch')
-    end
+    name = row[header_map[:name]]
+    name = email if name.blank?
 
-    row[0] = row[1] if row[0].blank?
-    role = parse_file_role(row[2])
-    phantom = parse_file_phantom(row[3])
-    if @current_course.show_personalized_timeline_features?
-      timeline_algorithm = parse_file_timeline_algorithm(row[4])
-      external_id = parse_file_external_id(row[5])
-    else
-      external_id = parse_file_external_id(row[4])
-      timeline_algorithm = parse_file_timeline_algorithm(nil)
-    end
-    { name: row[0], email: row[1], role: role, phantom: phantom,
+    role = parse_file_role(row_cell(row, header_map, :role))
+    phantom = parse_file_phantom(row_cell(row, header_map, :phantom))
+    timeline_algorithm = parse_file_timeline_algorithm(row_cell(row, header_map, :personal_timeline))
+    external_id = parse_file_external_id(row_cell(row, header_map, :external_id))
+
+    { name: name, email: email, role: role, phantom: phantom,
       timeline_algorithm: timeline_algorithm, external_id: external_id }
   end
 
+  def row_cell(row, header_map, col)
+    idx = header_map[col]
+    idx ? row[idx] : nil
+  end
+
   # Parses the role column from the CSV file.
   # This method handles the case where the role is not specified too, where "student" will be assumed.
   #

app/services/concerns/course/user_invitation_service/process_invitation_concern.rb

@@ -79,10 +79,13 @@ def handle_existing_course_user(user, course_user, existing_course_users)
     csv_ext_id = user[:external_id].presence
     current_ext_id = course_user.external_id.presence
 
-    if csv_ext_id.nil? || csv_ext_id == current_ext_id
-      existing_course_users << course_user
-    elsif @taken_external_ids.include?(csv_ext_id)
+    if @taken_external_ids.include?(csv_ext_id) && csv_ext_id != current_ext_id
       @failed_users.push(user.merge(reason: :external_id_taken))
+    elsif csv_ext_id.nil? || csv_ext_id == current_ext_id || @resolution == :keep_existing
+      existing_course_users << course_user
+    elsif @resolution.nil?
+      @pending_course_user_updates << { record: course_user, new_external_id: csv_ext_id,
+                                        previous_external_id: current_ext_id }
     else
       @taken_external_ids.delete(current_ext_id) if current_ext_id
       @taken_external_ids.add(csv_ext_id)
@@ -114,6 +117,7 @@ def build_course_user(user)
   # @param [Array<User>] users The users to ensure have instance users.
   # @return [void]
   def ensure_instance_users(users)
+    # instance_users must be preloaded (done by find_existing_users) — otherwise .any? fires N queries.
     missing_user_ids = users.reject { |user| user.instance_users.any? }.map(&:id)
     return if missing_user_ids.empty?
 
@@ -159,10 +163,14 @@ def handle_existing_invitation(user, invitation, existing_invitations)
 
     # Non-retryable invitations are surfaced as existing invitations, not errors —
     # the request succeeded; the prior delivery failure is informational.
-    if csv_ext_id.nil? || csv_ext_id == current_ext_id || invitation.is_retryable == false
-      existing_invitations << invitation
-    elsif @taken_external_ids.include?(csv_ext_id)
+    if @taken_external_ids.include?(csv_ext_id) && csv_ext_id != current_ext_id && invitation.is_retryable != false
       @failed_users.push(user.merge(reason: :external_id_taken))
+    elsif csv_ext_id.nil? || csv_ext_id == current_ext_id ||
+          invitation.is_retryable == false || @resolution == :keep_existing
+      existing_invitations << invitation
+    elsif @resolution.nil?
+      @pending_invitation_updates << { record: invitation, new_external_id: csv_ext_id,
+                                       previous_external_id: current_ext_id }
     else
       @taken_external_ids.delete(current_ext_id) if current_ext_id
       @taken_external_ids.add(csv_ext_id)

app/services/course/user_invitation_service.rb

@@ -6,6 +6,16 @@ class Course::UserInvitationService
   include ProcessInvitationConcern
   include EmailInvitationConcern
 
+  class PendingExternalIdUpdates < StandardError
+    attr_reader :pending_invitation_updates, :pending_course_user_updates
+
+    def initialize(pending_invitation_updates:, pending_course_user_updates:)
+      @pending_invitation_updates = pending_invitation_updates
+      @pending_course_user_updates = pending_course_user_updates
+      super('Pending external ID updates require confirmation')
+    end
+  end
+
   # Constructor for the user invitation service object.
   #
   # @param [CourseUser|nil] current_course_user The course user performing this action.
@@ -28,33 +38,27 @@ def initialize(current_course_user, current_user, current_course)
   #   existing_course_users, failed_users, updated_invitations, updated_course_users]
   #   if success. nil when fail.
   # @raise [CSV::MalformedCSVError] When the file provided is invalid.
-  def invite(users)
-    new_invitations = nil
-    existing_invitations = nil
-    new_course_users = nil
-    existing_course_users = nil
-    failed_users = nil
-    updated_invitations = nil
-    updated_course_users = nil
+  def invite(users, external_id_resolution: nil)
+    @resolution = external_id_resolution&.to_sym
+    result = nil
 
     success = Course.transaction do
-      new_invitations, existing_invitations,
-      new_course_users, existing_course_users,
-      failed_users, updated_invitations, updated_course_users = invite_users(users)
-      raise ActiveRecord::Rollback unless updated_invitations.all? { |u| u[:record].save }
-      raise ActiveRecord::Rollback unless updated_course_users.all? { |u| u[:record].save }
-      raise ActiveRecord::Rollback unless new_invitations.all?(&:save)
-      raise ActiveRecord::Rollback unless new_course_users.all?(&:save)
-
+      result = invite_users(users)
+      raise_if_pending_external_id_updates!
+      save_invitation_records!(result)
       true
     end
 
     return unless success
 
+    new_invitations, _, new_course_users, = result
     send_registered_emails(new_course_users)
     send_invitation_emails(new_invitations)
-    [new_invitations, existing_invitations, new_course_users, existing_course_users,
-     failed_users, updated_invitations, updated_course_users]
+    result
+  end
+
+  def blank_header_warning
+    @blank_header_warning || false
   end
 
   # Resends invitation emails to CourseUsers to the given course.
@@ -64,11 +68,28 @@ def invite(users)
   # @return [Boolean] True if there were no errors in sending invitations.
   #   If all provided CourseUsers have already registered, method also returns true.
   def resend_invitation(invitations)
-    invitations.blank? ? true : send_invitation_emails(invitations)
+    invitations.blank? || send_invitation_emails(invitations)
   end
 
   private
 
+  def raise_if_pending_external_id_updates!
+    return unless @pending_invitation_updates.any? || @pending_course_user_updates.any?
+
+    raise PendingExternalIdUpdates.new(
+      pending_invitation_updates: @pending_invitation_updates,
+      pending_course_user_updates: @pending_course_user_updates
+    )
+  end
+
+  def save_invitation_records!(result)
+    new_invitations, _, new_course_users, _, _, updated_invitations, updated_course_users = result
+    all_records = updated_invitations.map { |u| u[:record] } +
+                  updated_course_users.map { |u| u[:record] } +
+                  new_invitations + new_course_users
+    raise ActiveRecord::Rollback unless all_records.all?(&:save)
+  end
+
   # Invites the given users into the course.
   #
   # @param [Array<Hash>|File|TempFile] users Invites the given users.
@@ -93,6 +114,8 @@ def invite_users(users)
     @failed_users = parse_duplicates
     @updated_invitations = []
     @updated_course_users = []
+    @pending_invitation_updates = []
+    @pending_course_user_updates = []
     process_invitations(unique_users) + [@failed_users, @updated_invitations, @updated_course_users]
   end
 end

app/views/course/user_invitations/_pending_external_id_data.json.jbuilder

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+json.pendingInvitationUpdates pending_invitation_updates do |item|
+  inv = item[:record]
+  json.id                inv.id
+  json.name              inv.name
+  json.email             inv.email
+  json.externalId        item[:new_external_id]
+  json.previousExternalId item[:previous_external_id]
+  json.role              inv.role
+  json.phantom           inv.phantom
+  json.timelineAlgorithm inv.timeline_algorithm
+end
+
+json.pendingCourseUserUpdates pending_course_user_updates do |item|
+  cu = item[:record]
+  json.id                cu.id
+  json.name              cu.name.strip
+  json.email             cu.user.email
+  json.externalId        item[:new_external_id]
+  json.previousExternalId item[:previous_external_id]
+  json.role              cu.role
+  json.phantom           cu.phantom?
+  json.timelineAlgorithm cu.timeline_algorithm
+end