eco-helpers 1.5.1 → 1.5.2

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

@@ -1,18 +1,18 @@
 module Eco
   module API
     class MicroCases
-      #self.define("set_core") do |entry, person, session, options, people, supers|
-
+      # 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 [Person] the person we want to update, carrying the changes to be done.
+      # @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, people, supers_job)
+      def set_core(entry, person, options)
         unless options.dig(:exclude, :core) && !person.new?
           entry.set_core(person, exclude: micro.core_excluded(person, options))
           micro.fix_filter_tags(person, options)
-          micro.set_supervisor(entry, person, options, people, supers_job)
         end
       end
+
     end
   end
 end

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

@@ -0,0 +1,23 @@
+module Eco
+  module API
+    class MicroCases
+      # 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)
+        unless options.dig(:exclude, :core) && !person.new?
+          micro.set_core(entry, person, options)
+          micro.set_supervisor(entry.supervisor_id, person, people, options) do |unkown_id|
+            # delay setting supervisor if does not exit
+            supers_job.add(person) {|person| person.supervisor_id = unkown_id}
+          end
+        end
+      end
+
+    end
+  end
+end

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

@@ -1,26 +1,30 @@
 module Eco
   module API
     class MicroCases
-      #self.define("set_supervisor") do |entry, person, session, options, people, supers_job|
-
-      def set_supervisor(entry, person, options, people, supers_job)
-        # set supervisor
+      # Special snippet to decide if the `supervisor_id` is set now or in a later batch job `supers_job`.
+      # @note delaying the setting of a `supervisor_id` can save errors when the supervisor still does not exit.
+      # @param sup_id [nil, String] the **supervisor id** we should set on the `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 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(sup_id, person, people, options)
         unless options.dig(:exclude, :core) || options.dig(:exclude, :supervisor)
-          if !(sup_id = entry.supervisor_id)
-            person.supervisor_id = nil
-          else
-            if supervisor = people.person(id: sup_id, external_id: sup_id, email: sup_id)
+          micro.with_supervisor(sup_id, people) do |supervisor|
+            if !sup_id
+              person.supervisor_id = nil
+            elsif supervisor
               person.supervisor_id = supervisor.id
+            elsif !block_given?
+              person.supervisor_id = sup_id
             else
-              # delay setting supervisor if does not exit
-              supers_job.add(person) do |person|
-                person.supervisor_id = sup_id
-              end
+              yield(sup_id) if block_given?
             end
           end
         end
       end
-      
+
     end
   end
 end

data/lib/eco/api/microcases/strict_search.rb

@@ -1,14 +1,19 @@
 module Eco
   module API
     class MicroCases
-      #self.define("strict_search") do |session, options|
-
-      # @param options [Hash] the options
-      def strict_search(options)
-        strict_config = session.config.people.strict_search?
-        strict_option = !options[:search]&.key?(:strict) || options.dig(:search, :strict)
-        strict_config && strict_option
+      # When trying to find an `person` with given a source `entry`, it states if such a search should be `strict` or `soft`.
+      # @note
+      #   - `strict` searches ignore the email when the source `entry` has an `external_id` specified.
+      #   - see related command line options `-search-strict` and `-search-soft`
+      # @param options [Hash] the options.
+      # @return [Boolean] `true` if the search should be `strict` only, and `false` otherwise.
+      def strict_search?(options)
+        strict_config  = session.config.people.strict_search?
+        strict_option  = options.dig(:search, :strict)
+        soft_option    = options.dig(:search, :soft) && !strict_option
+        (strict_config || strict_option) && !soft_option
       end
+
     end
   end
 end

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

@@ -0,0 +1,27 @@
+module Eco
+  module API
+    class MicroCases
+      # 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.
+      # @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)
+        entries.map do |entry|
+          unless person = people.find(entry, strict: micro.strict_search?(options))
+            person = session.new_person
+          end
+          person.entry = entry
+          yield(entry, person) if block_given?
+          person
+        end.yield_self {|all_people| people.newFrom all_people.uniq}
+      end
+
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+module Eco
+  module API
+    class MicroCases
+      # 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
+      # @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

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

@@ -0,0 +1,30 @@
+module Eco
+  module API
+    class MicroCases
+      # 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? && log_starter
+            session.logger.error("This person does not exist: #{entry.to_s(:identify)}")
+            next
+          end
+          found << person
+          yield(entry, person) if block_given?
+        end
+        people.newFrom found
+      end
+
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+module Eco
+  module API
+    class MicroCases
+      # 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`.
+      # @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)
+        starters = []
+        micro.with_each(entries, people, options) do |entry, person|
+          if !person.new? && log_present
+            session.logger.error("This person (id: '#{person.id}') already exists: #{entry.to_s(:identify)}")
+            next
+          end
+          staters << person
+          yield(entry, person) if block_given?
+        end
+        people.newFrom starters
+      end
+
+    end
+  end
+end

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

@@ -0,0 +1,34 @@
+module Eco
+  module API
+    class MicroCases
+      # 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

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

@@ -0,0 +1,36 @@
+module Eco
+  module API
+    class MicroCases
+      # 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 nil if value.to_s.strip.empty?
+        case
+        when value.respond_to?(:supervisor_id)
+          value.supervisor_id
+        when value.is_a?(Hash)
+          value["supervisor_id"]
+        else
+          value
+        end
+      end
+
+    end
+  end
+end

data/lib/eco/api/organization/people.rb

@@ -3,24 +3,18 @@ module Eco
     module Organization
       class People <  Eco::Language::Models::Collection
         # build the shortcuts of Collection
-        attr_collection :id, :external_id, :email, :name, :supervisor_id
         attr_presence :account, :details
+        attr_collection :id, :external_id, :email, :name, :supervisor_id
 
         alias_method :people, :to_a
 
-        def initialize(people = [], klass: Ecoportal::API::Internal::Person, factory: nil)
+        def initialize(people = [], klass: Ecoportal::API::Internal::Person)
           @klass = Ecoportal::API::Internal::Person unless klass == Ecoportal::API::V1::Person
           super(people, klass: @klass)
           @caches_init = false
         end
 
-        def to_json
-          to_a.to_json
-        end
-
-        def [](id_or_ext)
-          id(id_or_ext) || external_id(id_or_ext)
-        end
+        # @!group Main identifier helpers
 
         def id(*args)
           attr('id', *args).first
@@ -30,6 +24,13 @@ module Eco
           attr('external_id', *args).first
         end
 
+        def [](id_or_ext)
+          id(id_or_ext) || external_id(id_or_ext)
+        end
+        # @!endgroup
+
+        # @!group Special filters
+
         def users
           account_present(true)
         end
@@ -42,7 +43,41 @@ module Eco
           account_present(false)
         end
 
-        # It searches a person using the paramters given.
+        def supervisors
+          sup_ids = self.ids & self.supervisor_ids
+          sup_ids.map do |id|
+            person(id: id, strict: true)
+          end.yield_self do |supervisors|
+            newFrom supervisors
+          end
+        end
+
+        def missing_supervisors_ids
+          sup_ids = self.supervisor_ids
+          sup_ids - (sup_ids & self.ids)
+        end
+
+        def filter_tags_any(tags)
+          attr("filter_tags", tags, default_modifier.any.insensitive)
+        end
+
+        def filter_tags_all(tags)
+          attr("filter_tags", tags, default_modifier.all.insensitive)
+        end
+
+        def policy_group_ids_any(ids)
+          attr("policy_group_ids", tags, default_modifier.any.insensitive)
+        end
+
+        def policy_group_ids_all(ids)
+          attr("policy_group_ids", tags, default_modifier.all.insensitive)
+        end
+
+        # @!endgroup
+
+        # @!group Searchers
+
+        # It searches a person using the parameters given.
         # @param id [String] the `internal id` of the person
         # @param external_id [String] the `exernal_id` of the person
         # @param email [String] the `email` of the person
@@ -72,23 +107,34 @@ module Eco
         end
 
         def find(object, strict: false)
-          id          = object.respond_to?("id")?          object.send("id") : nil
-          external_id = object.respond_to?("external_id")? object.send("external_id") : nil
-          email       = object.respond_to?("email")?       object.send("email") : nil
+          id          = attr_value(object, "id")
+          external_id = attr_value(object, "external_id")
+          email       = attr_value(object, "email")
           person(id: id, external_id: external_id, email: email, strict: strict)
         end
+        # @!endgroup
+
+        # @!group Basic Collection Methods
+
+        def to_json
+          to_a.to_json
+        end
+
+        def newFrom(data)
+          self.class.new(data, klass: @klass)
+        end
 
         def uniq(strict: false, include_unsearchable: false)
-          init_caches
           unsearchable = []
-          newFrom to_a.each_with_object([]) do |person, people|
+          to_a.each_with_object([]) do |person, people|
             if found = find(person, strict: strict)
               people << found
             else
               unsearchable << person
             end
-          end.tap do |people|
-            people << unsearchable if include_unsearchable
+          end.yield_self do |found|
+            found += unsearchable if include_unsearchable
+            newFrom found
           end
         end
 
@@ -103,15 +149,19 @@ module Eco
         end
 
         def exclude!(object, strict: false)
-          self < exclude(object, strict: strict).to_a
+          self < exclude(object, strict: strict)
         end
 
         def exclude_people(list, strict: false)
-          discarded = list.map do |person|
+          list.map do |person|
             find(person, strict: strict)
-          end.compact
-          newFrom to_a - discarded
+          end.compact.yield_self do |discarded|
+            newFrom to_a - discarded
+          end
         end
+        # @!endgroup
+
+        # @!group Groupping methods
 
         def email_id_maps
           users.group_by(:email).transform_values { |person| person.id }
@@ -121,23 +171,10 @@ module Eco
           to_h(:supervisor_id)
         end
 
-        # only those that are present
-        def supervisors
-          h_all = self.to_h
-          sup_ids = h_all.keys & self.supervisor_ids
-          newFrom h_all.select do |id, person|
-            sup_ids.include?(id)
-          end.values
-        end
-
-        def missing_supervisors_ids
-          sup_ids = self.supervisor_ids
-          sup_ids - (sup_ids & self.ids)
-        end
-
         def to_h(attr = "id")
           super(attr || "id")
         end
+        # @!endgroup
 
         protected