eco-helpers 3.0.20 → 3.0.22

data/lib/eco/api/error/handlers.rb

@@ -5,7 +5,7 @@ module Eco
         autoloads_children_of "Eco::API::Common::Loaders::ErrorHandler"
         autoload_namespace_ignore "Eco::API"
 
-        def define(*args)
+        def define(*_args)
           raise "Missusage. You should use 'on' method instead"
         end
 
@@ -13,16 +13,23 @@ module Eco
         def on(klass_err, type: :error_handler, retry: true, &block)
           Eco::API::Error.validate_err_class(klass_err)
           raise "Expected block but not given" unless block
-          Eco::API::Error::Handler.new(klass_err, type: type, root: self, &block).tap do |handler|
+
+          Eco::API::Error::Handler.new(
+            klass_err,
+            type: type,
+            root: self,
+            &block
+          ).tap do |handler|
             add(handler)
           end
         end
 
         def add(handler)
-          raise "Expected Eco::API::Error::Handler object. Given: #{policy}" unless handler.is_a?(Eco::API::Error::Handler)
-          super(handler)
-        end
+          msg = "Expected Eco::API::Error::Handler object. Given: #{handler.class}"
+          raise ArgumentError, msg unless handler.is_a?(Eco::API::Error::Handler)
 
+          super
+        end
       end
     end
   end

data/lib/eco/api/microcases/people/apply_changes/set_account/account_excluded.rb

@@ -0,0 +1,34 @@
+module Eco
+  module API
+    class MicroCases
+      module People
+        module ApplyChanges
+          module SetAccount
+            module AccountExcluded
+              # @param person [Ecoportal::API::V1::Person] the person we want to update, carrying the changes to be done.
+              # @param options [Hash] the options.
+              # @return [Array<String>] the account parameters that should not be included.
+              def account_excluded(person, options)
+                [].tap do |account_excluded|
+                  next if person.new?
+
+                  if options.dig(:exclude, :policy_groups)
+                    account_excluded.push('policy_group_ids')
+                  end
+
+                  if options.dig(:exclude, :default_tag)
+                    account_excluded.push('default_tag')
+                  end
+
+                  if options.dig(:exclude, :login_providers)
+                    account_excluded.push('login_provider_ids')
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/eco/api/microcases/people/apply_changes/set_account.rb

@@ -0,0 +1,28 @@
+require_relative 'set_account/account_excluded'
+
+module Eco
+  module API
+    class MicroCases
+      module People
+        module ApplyChanges
+          module SetAccount
+            include AccountExcluded
+
+            # @param entry [PersonEntry] the input entry with the data we should set on person.
+            # @param person [Ecoportal::API::V1::Person] the person we want to update, carrying the changes to be done.
+            # @param options [Hash] the options.
+            def set_account(entry, person, options)
+              return if options.dig(:exclude, :account)
+
+              entry.set_account(person, exclude: micro.account_excluded(person, options))
+
+              person.account.send_invites = options[:send_invites] if options.key?(:send_invites)
+              micro.refresh_default_tag(entry, person, options)
+              micro.fix_default_group(entry, person, options)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/eco/api/microcases/people/apply_changes/set_core/core_excluded.rb

@@ -0,0 +1,28 @@
+module Eco
+  module API
+    class MicroCases
+      module People
+        module ApplyChanges
+          module SetCore
+            module CoreExcluded
+              # @note by default `supervisor_id` is always excluded.
+              # @param person [Ecoportal::API::V1::Person] the person we want to update, carrying the changes to be done.
+              # @param options [Hash] the options.
+              # @return [Array<String>] the core parameters that should not be included.
+              def core_excluded(person, options)
+                ['supervisor_id'].tap do |core_excluded|
+                  can_exclude = person.new?? ['filter_tags'] : %w[name external_id email filter_tags]
+
+                  exclusions  = can_exclude.select do |attr|
+                    options.dig(:exclude, attr.to_sym)
+                  end
+                  core_excluded.concat(exclusions)
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/eco/api/microcases/people/apply_changes/set_core.rb

@@ -0,0 +1,27 @@
+require_relative 'set_core/core_excluded'
+
+module Eco
+  module API
+    class MicroCases
+      module People
+        module ApplyChanges
+          module SetCore
+            include CoreExcluded
+
+            # Sets all the core details, but the supervisor.
+            # @note `supervisor_id` requires a special treatment, and therefore is always excluded.
+            # @param entry [PersonEntry] the input entry with the data we should set on person.
+            # @param person [Ecoportal::API::V1::Person] the person we want to update, carrying the changes to be done.
+            # @param options [Hash] the options
+            def set_core(entry, person, options)
+              return if options.dig(:exclude, :core) && !person.new?
+
+              entry.set_core(person, exclude: micro.core_excluded(person, options))
+              micro.fix_filter_tags(person, options)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/eco/api/microcases/people/apply_changes/set_core_with_supervisor.rb

@@ -0,0 +1,38 @@
+module Eco
+  module API
+    class MicroCases
+      module People
+        module ApplyChanges
+          module SetCoreWithSupervisor
+            # Sets all the core details, but the supervisor.
+            # @note `supervisor_id` requires a special treatment, and therefore is always excluded.
+            # @param entry [PersonEntry] the input entry with the data we should set on person.
+            # @param person [Ecoportal::API::V1::Person] the person we want to update, carrying the changes to be done.
+            # @param people [Eco::API::Organization::People] target existing _People_ of the current update.
+            # @param supers_job [Eco::API::Session::Batch::Job] the job that will run the supers .
+            # @param options [Hash] the options.
+            def set_core_with_supervisor(entry, person, people, supers_job, options)
+              return if options.dig(:exclude, :core) && !person.new?
+
+              micro.set_core(entry, person, options)
+
+              return unless entry.supervisor_id?
+
+              micro.set_supervisor(
+                person,
+                entry.supervisor_id,
+                people,
+                options
+              ) do |unknown_id|
+                # delay setting supervisor if does not exit
+                supers_job.add(person) do |pers|
+                  micro.set_supervisor(pers, unknown_id, people, options)
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/eco/api/microcases/people/apply_changes/set_supervisor.rb

@@ -0,0 +1,69 @@
+module Eco
+  module API
+    class MicroCases
+      module People
+        module ApplyChanges
+          module SetSupervisor
+            # Unique access point to set the `supervisor_id` value on a person.
+            # @note
+            #   - It prevents the basic cyclic supervisor case (supervisor to be supervisor of themselves)
+            # @param person [Ecoportal::API::V1::Person] the person we want to update, carrying the changes to be done.
+            # @param sup_id [nil, String] the **supervisor id** we should set on the `person`.
+            # @param people [Eco::API::Organization::People] _People_ involved in the current update.
+            # @param options [Hash] the options.
+            # @yield [supervisor_id] callback when the supervisor_id is **unknown** (not `nil` nor any one's in `people`).
+            # @yieldparam supervisor_id [String] the **unknown** `supervisor_id`.
+            def set_supervisor(person, sup_id, people, options)
+              return false if options.dig(:exclude, :core) || options.dig(:exclude, :supervisor)
+              return false if sup_id && ((person.id == sup_id) || (person.external_id == sup_id))
+
+              cur_id    = person.supervisor_id
+              cur_super = cur_id && with_supervisor(cur_id, people)
+
+              micro.with_supervisor(sup_id, people) do |new_super|
+                if !sup_id
+                  person.supervisor_id = nil
+                  descrease_subordinates(cur_super)
+                elsif new_super && (id = new_super.id)
+                  set_supervisor(new_super, nil, people, options) if new_super_direct_cyclic?(person, new_super)
+                  person.supervisor_id = id
+                  descrease_subordinates(cur_super)
+                  increase_subordinates(new_super)
+                elsif !block_given?
+                  descrease_subordinates(cur_super)
+                  person.supervisor_id = sup_id
+                elsif block_given?
+                  yield(sup_id)
+                end
+              end
+            end
+
+            private
+
+            def new_super_direct_cyclic?(person, new_super)
+              return false unless new_super.is_a?(Ecoportal::API::V1::Person)
+              return false if new_super.supervisor_id.nil?
+              return true  if person.id == new_super.id
+              return true  if new_super.supervisor_id == person.id
+              return true  if new_super.supervisor_id == person.external_id
+
+              false
+            end
+
+            def descrease_subordinates(person, by = 1)
+              return unless person.is_a?(Ecoportal::API::V1::Person)
+
+              person.subordinates -= by
+            end
+
+            def increase_subordinates(person, by = 1)
+              return unless person.is_a?(Ecoportal::API::V1::Person)
+
+              person.subordinates += by
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/eco/api/microcases/people/apply_changes.rb

@@ -0,0 +1,19 @@
+require_relative 'apply_changes/set_core'
+require_relative 'apply_changes/set_supervisor'
+require_relative 'apply_changes/set_core_with_supervisor'
+require_relative 'apply_changes/set_account'
+
+module Eco
+  module API
+    class MicroCases
+      module People
+        module ApplyChanges
+          include SetCore
+          include SetSupervisor
+          include SetCoreWithSupervisor
+          include SetAccount
+        end
+      end
+    end
+  end
+end

data/lib/eco/api/microcases/people/fetch/with_each.rb

@@ -0,0 +1,109 @@
+module Eco
+  module API
+    class MicroCases
+      module People
+        module Fetch
+          module WithEach
+            # Finds each **entry** of `entries` in `people` and runs a block.
+            # @note
+            #  - it also links to `person.entry` the input data entry.
+            # @param entries [Eco::API::Common::People::Entries] the input entries with the data.
+            # @param people [Eco::API::Organization::People] target existing _People_ of the current update.
+            # @param options [Hash] the options.
+            # @param append_created [Boolean] whether or not a new person will be added to the `people` object.
+            # @yield [entry, person] gives each entry, and the paired person thereof (new or existing).
+            # @yieldparam entry [PersonEntry] the input entry with the data we should set on person.
+            # @yieldparam person [Ecoportal::API::V1::Person] the found person that matches `entry`, or a new person otherwise.
+            # @return [Eco::API::Organization::People] all the people, including new and existing ones.
+            def with_each(entries, people, options, append_created: true)
+              @_skip_all_multiple_results = false
+              people_copy = people.newFrom(people.to_a)
+
+              entries.each_with_object([]) do |entry, scoped|
+                begin
+                  person   = people_copy.find(entry, strict: micro.strict_search?(options))
+                  person ||= session.new_person.tap do |pers|
+                    people << pers if append_created
+                  end
+                rescue Eco::API::Organization::People::MultipleSearchResults => e
+                  unless @_skip_all_multiple_results
+                    msg    = "\n * When searching this Entry: #{entry.to_s(:identify)}"
+                    person = _with_each_prompt_to_select_user(e.append_message(msg), entry: entry)
+                  end
+                end
+
+                next unless person
+
+                person.entry = entry
+                yield(entry, person) if block_given?
+
+                scoped << person
+              end.then do |all_people|
+                people.newFrom all_people.uniq
+              end
+            end
+
+            private
+
+            def _with_each_prompt_to_select_user(error, entry: nil, increase_count: true) # rubocop:disable Metrics/AbcSize
+              unless error.is_a?(Eco::API::Organization::People::MultipleSearchResults)
+                raise "Expecting Eco::API::Organization::People::MultipleSearchResults. Given: #{error.class}"
+              end
+
+              @_with_each_prompts  = 0 unless instance_variable_defined?(:@_with_each_prompts)
+              @_with_each_prompts += 1 if increase_count
+
+              lines  = []
+              lines << "\n(#{@_with_each_prompts}) #{error}\n"
+              lines << '  #index   - Select the correct person by its number index among the list above.'
+              lines << '  (I)      - Just Skip/Ignore this one. I will deal with that input entry in another launch.'
+              lines << '  (A)      - Ignore all the rest of input entries with this problem.'
+              lines << '  (C)      - Create a new person.'
+              lines << '  (B)      - Just break this script. I need to change the input file :/'
+
+              prompt_user('Type one option (#number/I/A/C/B):', explanation: lines.join("\n"), default: 'I') do |res|
+                res = res.upcase
+
+                if res.start_with?('I')
+                  log(:info) { "Ignoring entry... #{entry&.to_s(:identify)}" }
+
+                  nil
+                elsif res.start_with?('A')
+                  log(:info) {
+                    'All input entries with this same issue will be ignored for this launch'
+                  }
+
+                  @_skip_all_multiple_results = true
+                  nil
+                elsif res.start_with?('C')
+                  log(:info) {
+                    "Creating new person...#{"for entry #{entry.to_s(:identify)}" if entry}"
+                  }
+
+                  session.new_person
+                elsif res.start_with?('B')
+                  raise error
+                elsif res && !res.empty? && (pos = res.to_i rescue nil) && (pos < error.candidates.length) # rubocop:disable Style/RescueModifier
+                  error.candidate(pos).tap do |person|
+                    log(:info) { "Thanks!! You selected #{person.identify}" }
+                    sleep(1.5)
+                  end
+                else
+                  if pos.is_a?(Numeric) && (pos >= error.candidates.length)
+                    print "#{pos} is not a number in the range. "
+                  else
+                    print "#{res} is not an option. "
+                  end
+
+                  puts 'Please select one of the offered options...'
+                  sleep(1)
+                  _with_each_prompt_to_select_user(error, increase_count: false, entry: entry)
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/eco/api/microcases/people/fetch/with_each_leaver.rb

@@ -0,0 +1,33 @@
+module Eco
+  module API
+    class MicroCases
+      module People
+        module Fetch
+          module WithEachLeaver
+            # Detects who has left the organization and `yield` s them one by one to the given block
+            # @note
+            #   - To be used only when the input file is the full DB
+            #   - The `Entries#find` method. If the people manager entry does not have `external_id`,
+            #     but has a matching `email` wiht some input entry (row), it won't be identified as a leaver.
+            # @param entries [Eco::API::Common::People::Entries] the input entries with the data.
+            # @param people [Eco::API::Organization::People] target existing _People_ of the current update.
+            # @param options [Hash] the options.
+            # @yield [person] gives each person of `people` that is not present in `entries`.
+            # @yieldparam person [Ecoportal::API::V1::Person] the person that leaves the org.
+            # @return [Eco::API::Organization::People] the leavers.
+            def with_each_leaver(entries, people, options)
+              leavers = people.map do |person|
+                unless entries.find(person, strict: micro.strict_search?(options))
+                  yield(person) if block_given?
+                  person
+                end
+              end.compact
+
+              people.newFrom leavers
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/eco/api/microcases/people/fetch/with_each_present.rb

@@ -0,0 +1,42 @@
+module Eco
+  module API
+    class MicroCases
+      module People
+        module Fetch
+          module WithEachPresent
+            # Finds those in `entries` that already exist in the organization (`people`) and `yield` s them one by one to the given block.
+            # @note
+            #   - it also links to `person.entry` the input data `entry`.
+            # @param entries [Eco::API::Common::People::Entries] the input entries with the data.
+            # @param people [Eco::API::Organization::People] target existing _People_ of the current update.
+            # @param options [Hash] the options.
+            # @param log_starter [Boolean] log error message if an `entry` does not have match in `people`.
+            # @yield [entry, person] gives each **found** `person` of `entries` that is not present in `people`.
+            # @yieldparam entry [PersonEntry] the input entry with the data we should set on person.
+            # @yieldparam person [Ecoportal::API::V1::Person] the **found** person.
+            # @return [Eco::API::Organization::People] the found people.
+            def with_each_present(entries, people, options, log_starter: false)
+              found = []
+              micro.with_each(entries, people, options) do |entry, person|
+                if person.new?
+                  if log_starter
+                    log(:error) {
+                      "This person does not exist: #{entry.to_s(:identify)}"
+                    }
+                  end
+
+                  next
+                end
+
+                found << person
+                yield(entry, person) if block_given?
+              end
+
+              people.newFrom found
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/eco/api/microcases/people/fetch/with_each_starter.rb

@@ -0,0 +1,43 @@
+module Eco
+  module API
+    class MicroCases
+      module People
+        module Fetch
+          module WithEachStarter
+            # Detects who in the `entries` is new in the organization and `yield` s them one by one to the given block.
+            # @note
+            #   - it also links to `person.entry` the input data `entry`.
+            # @param entries [Eco::API::Common::People::Entries] the input entries with the data.
+            # @param people [Eco::API::Organization::People] target existing _People_ of the current update.
+            # @param options [Hash] the options.
+            # @param log_present [Boolean] log error message if an `entry` has match in `people`.
+            # @param append_created [Boolean] whether or not a new person will be added to the `people` object.
+            # @yield [entry, person] gives each **new** `person` of `entries` that is not present in `people`.
+            # @yieldparam entry [PersonEntry] the input entry with the data we should set on person.
+            # @yieldparam person [Ecoportal::API::V1::Person] the **new** person.
+            # @return [Eco::API::Organization::People] the starters.
+            def with_each_starter(entries, people, options, log_present: false, append_created: true)
+              starters = []
+              micro.with_each(entries, people, options, append_created: append_created) do |entry, person|
+                unless person.new?
+                  if log_present
+                    log(:error) {
+                      "This person (id: '#{person.id}') already exists: #{entry.to_s(:identify)}"
+                    }
+                  end
+
+                  next
+                end
+
+                starters << person
+                yield(entry, person) if block_given?
+              end
+
+              people.newFrom starters
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/eco/api/microcases/people/fetch/with_each_subordinate.rb

@@ -0,0 +1,41 @@
+module Eco
+  module API
+    class MicroCases
+      module People
+        module Fetch
+          module WithEachSubordinate
+            # Finds all the subordinates of `supervisor`.
+            # @note if `supervisor` is `nil`, it will return all people with no supervisor.
+            # @param supervisor [String, Ecoportal::API::V1::Person, Hash] the `supervisor` or the `id` / `external_id` thereof.
+            # @param people [Eco::API::Organization::People] target existing _People_ of the current update.
+            # @yield [subordinate] block that does some stuff with `subordinate`.
+            # @yieldparam subordinate [Ecoportal::API::V1::Person] each one of the suborinates of `supervisor`.
+            # @return [Eco::API::Organization::People] the **subordinates** of `supervisor`.
+            def with_each_subordinate(supervisor, people)
+              people.supervisor_id(
+                _person_id(supervisor, people)
+              ).tap do |subordinates|
+                subordinates.each do |subordinate|
+                  yield(subordinate) if block_given?
+                end
+              end
+            end
+
+            private
+
+            def _person_id(value, people)
+              case value
+              when Hash
+                _person_id(value['id'] || value['external_id'], people)
+              when Ecoportal::API::V1::Person
+                _person_id(value.id    || value.external_id, people)
+              when String
+                micro.with_supervisor(value, people)&.id
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/eco/api/microcases/people/fetch/with_supervisor.rb

@@ -0,0 +1,46 @@
+module Eco
+  module API
+    class MicroCases
+      module People
+        module Fetch
+          module WithSupervisor
+            # Finds the supervisor among `people` by using the `supervisor_id` of `value`.
+            # @param value [String, Ecoportal::API::V1::Person, Hash] the subordinate person,
+            #   or the unique identifier of the supervisor to be found (preferably the `external_id`).
+            # @param people [Eco::API::Organization::People] target existing _People_ of the current update.
+            # @param strict [Boolean] specifies if the search should be `strict` (see {Eco::API::Organization::People#person}).
+            # @yield [supervisor] block that does some stuff with supevisor.
+            # @yieldparam supervisor [Ecoportal::API::V1::Person] the person object of the supervisor, or `nil` if not found.
+            # @return [nil, Ecoportal::API::V1::Person] found `supervisor` of `value`.
+            def with_supervisor(value, people, strict: false)
+              if (sup_id = with_supervisor_supervisor_id(value))
+                people.person(
+                  id:          sup_id,
+                  external_id: sup_id,
+                  email:       sup_id,
+                  strict:      strict
+                )
+              end.tap do |supervisor|
+                yield(supervisor) if block_given?
+              end
+            end
+
+            private
+
+            def with_supervisor_supervisor_id(value)
+              return if value.to_s.strip.empty?
+
+              if value.respond_to?(:supervisor_id)
+                value.supervisor_id
+              elsif value.is_a?(Hash)
+                value['supervisor_id']
+              else
+                value
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/eco/api/microcases/people/fetch.rb

@@ -0,0 +1,23 @@
+require_relative 'fetch/with_supervisor'
+require_relative 'fetch/with_each'
+require_relative 'fetch/with_each_present'
+require_relative 'fetch/with_each_starter'
+require_relative 'fetch/with_each_leaver'
+require_relative 'fetch/with_each_subordinate'
+
+module Eco
+  module API
+    class MicroCases
+      module People
+        module Fetch
+          include WithSupervisor
+          include WithEach
+          include WithEachPresent
+          include WithEachStarter
+          include WithEachLeaver
+          include WithEachSubordinate
+        end
+      end
+    end
+  end
+end

data/lib/eco/api/microcases/people/integrity/fix_default_group.rb

@@ -0,0 +1,39 @@
+module Eco
+  module API
+    class MicroCases
+      module People
+        module Integrity
+          module FixDefaultGroup
+            # If defined, it sets the default usergroup, only when the `policy_group_ids` was not part of the input data.
+            # @param entry [PersonEntry] the input entry with the data we should set on person.
+            # @param person [Ecoportal::API::V1::Person] the person we want to update, carrying the changes to be done.
+            # @param options [Hash] the options.
+            def fix_default_group(entry, person, options)
+              return if options.dig(:exclude, :account)
+              return if options.dig(:exclude, :policy_groups) && !person.new?
+
+              end_pg_ids = person.account.policy_group_ids
+
+              if person.account_added? && __def_usergroup_id && !entry.policy_group_ids?
+                # on account creation, if missing policy_group_ids column in the input
+                # use default_usergroup, if it's defined
+                end_pg_ids = [__def_usergroup_id]
+              end
+
+              person.account.policy_group_ids = end_pg_ids
+            end
+
+            private
+
+            def __def_usergroup_id
+              @__def_usergroup_id ||=
+                if session.config.people.default_usergroup?
+                  session.policy_groups.to_id(session.config.people.default_usergroup)
+                end
+            end
+          end
+        end
+      end
+    end
+  end
+end