feat(invitations): add external ID field, CSV header validation, and multi-language parsing

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]
@@ -93,7 +105,7 @@ def resend_invitation_params
   #   1) Single invitation - specified with the user_invitation_id param
   #   2) All un-confirmed invitation - if user_invitation_id param was not found
   def load_invitations
-    @invitations ||= begin
+    @load_invitations ||= begin
       ids = resend_invitation_params
       ids ||= current_course.invitations.retryable.unconfirmed.select(:id)
       if ids.blank?
@@ -118,12 +130,18 @@ def invite_by_file?
 
   # 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)
+    invitation_service.invite(invitation_params,
+                              external_id_resolution: params[:external_id_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.

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,10 @@ 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
+  EXPECTED_WITH_TIMELINE = Set.new(%i[name email external_id role phantom personal_timeline]).freeze
+  EXPECTED_WITHOUT_TIMELINE = Set.new(%i[name email external_id role phantom]).freeze
 
   private
 
@@ -111,28 +116,22 @@ 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
     [].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 = 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 = build_header_map!(row)
+          next
+        end
+        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.
@@ -143,29 +142,59 @@ 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
+  end
+
+  def expected_canonical_set
+    @current_course.show_personalized_timeline_features? ? EXPECTED_WITH_TIMELINE : EXPECTED_WITHOUT_TIMELINE
+  end
+
+  def build_header_map!(row)
+    resolved = row.each_with_index.each_with_object({}) do |(cell, idx), map|
+      canonical = header_alias_map[normalize_header(cell)]
+      map[canonical] = idx if canonical
+    end
+
+    resolved_set = Set.new(resolved.keys)
+    unless resolved_set == expected_canonical_set
+      expected_display = expected_canonical_set.map do |col|
+        I18n.t("csv.course_user_invitations.headers.#{col}")
+      end.join(', ')
+      raise I18n.t('errors.course.user_invitations.invalid_headers', expected: expected_display)
+    end
+
+    resolved
+  end
+
   # Parses the given CSV row (array) and returns attributes for a user invitation.
   #   - 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.
   # @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[header_map[:role]])
+    phantom = parse_file_phantom(row[header_map[:phantom]])
+    timeline_idx = header_map[:personal_timeline]
+    timeline_algorithm = parse_file_timeline_algorithm(timeline_idx ? row[timeline_idx] : nil)
+    external_id = parse_file_external_id(row[header_map[:external_id]])
+
+    { name: name, email: email, role: role, phantom: phantom,
       timeline_algorithm: timeline_algorithm, external_id: external_id }
   end
 

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

@@ -84,10 +84,24 @@ def handle_existing_course_user(user, course_user, existing_course_users)
     elsif @taken_external_ids.include?(csv_ext_id)
       @failed_users.push(user.merge(reason: :external_id_taken))
     else
-      @taken_external_ids.delete(current_ext_id) if current_ext_id
-      @taken_external_ids.add(csv_ext_id)
-      course_user.external_id = csv_ext_id
-      @updated_course_users << { record: course_user, previous_external_id: current_ext_id }
+      case @resolution
+      when :replace_all
+        @taken_external_ids.delete(current_ext_id) if current_ext_id
+        @taken_external_ids.add(csv_ext_id)
+        course_user.external_id = csv_ext_id
+        @updated_course_users << { record: course_user, previous_external_id: current_ext_id }
+      when :keep_existing
+        existing_course_users << course_user
+      else
+        @taken_external_ids.delete(current_ext_id) if current_ext_id
+        @taken_external_ids.add(csv_ext_id)
+        @pending_course_user_updates << {
+          record: course_user,
+          previous_external_id: current_ext_id,
+          new_external_id: csv_ext_id
+        }
+        existing_course_users << course_user
+      end
     end
   end
 
@@ -164,10 +178,24 @@ def handle_existing_invitation(user, invitation, existing_invitations)
     elsif @taken_external_ids.include?(csv_ext_id)
       @failed_users.push(user.merge(reason: :external_id_taken))
     else
-      @taken_external_ids.delete(current_ext_id) if current_ext_id
-      @taken_external_ids.add(csv_ext_id)
-      invitation.external_id = csv_ext_id
-      @updated_invitations << { record: invitation, previous_external_id: current_ext_id }
+      case @resolution
+      when :replace_all
+        @taken_external_ids.delete(current_ext_id) if current_ext_id
+        @taken_external_ids.add(csv_ext_id)
+        invitation.external_id = csv_ext_id
+        @updated_invitations << { record: invitation, previous_external_id: current_ext_id }
+      when :keep_existing
+        existing_invitations << invitation
+      else
+        @taken_external_ids.delete(current_ext_id) if current_ext_id
+        @taken_external_ids.add(csv_ext_id)
+        @pending_invitation_updates << {
+          record: invitation,
+          previous_external_id: current_ext_id,
+          new_external_id: csv_ext_id
+        }
+        existing_invitations << invitation
+      end
     end
   end
 

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,23 @@ def initialize(current_course_user, current_user, current_course)
   #   new_course_users, existing_course_users, failed_users, updated_invitations, updated_course_users
   #   respectively 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
 
   # Resends invitation emails to CourseUsers to the given course.
@@ -64,11 +64,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.
@@ -88,6 +105,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