eco-helpers 2.0.22 → 2.0.27

data/lib/eco/api/common/people/entries.rb

@@ -5,6 +5,42 @@ module Eco
         # Class meant to offer a _collection_ of entries, normally used to get parsed input data.
         # @attr_reader entries [Array<Eco::API::Common::PeopleEntry] a pure `Array` object.
         class Entries <  Eco::Language::Models::Collection
+          # Error class that allows to handle cases where multiple entries were found for the same criterion.
+          # @note its main purpose to prevent the false pairing of duplicates or override information between different people.
+          class MultipleSearchResults < StandardError
+            attr_reader :candidates, :property
+            # @param msg [String] the basic message error.
+            # @param candiates [Array<PersonEntry>] the entries that match the same search criterion.
+            # @param property [String] the property of the entry model that triggered the error (base of the search criterion).
+            def initialize(msg, candidates: [], property: "email")
+              @candidates = candidates
+              @property   = property
+              super(msg + " " + candidates_summary)
+            end
+
+            # @param with_index [Boolean] to add an index to each candidate description.
+            # @return [Array<String>] the `candidates` identified
+            def identify_candidates(with_index: false)
+              candidates.map.each_with_index do |entry, i|
+                index = with_index     ? "#{i}. " : ""
+                "#{index} #{entry.identify}"
+              end
+            end
+
+            # @return [Person] the `candidate` in the `index` position
+            def candidate(index)
+              candidates[index]
+            end
+
+            private
+
+            def candidates_summary
+              lines = ["The following entries have the same '#{property}':"]
+              lines.concat(identify_candidates(with_index: true)).join("\n  ")
+            end
+
+          end
+
           # build the shortcuts of Collection
           attr_collection :id, :external_id, :email, :name, :supervisor_id
 
@@ -54,19 +90,34 @@ module Eco
           # @!group Searchers
 
           # Search function to find an `entry` based on one of different options
+          #   It searches an entry using the parameters given.
+          # @note This is how the search function actually works:
+          #   1. if eP `id` is given, returns the entry (if found), otherwise...
+          #   2. if `external_id` is given, returns the entry (if found), otherwise...
+          #   3. if `strict` is `false` and `email` is given:
+          #     - if there is only 1 entry with that email, returns that entry, otherwise...
+          #     - if found but, there are many candidate entries, it raises MultipleSearchResults error
+          #     - if entry `external_id` matches `email`, returns that entry
+          # @raise MultipleSearchResults if there are multiple entries with the same `email`
+          #   and there's no other criteria to find the entry. It only gets to this point if
+          #   `external_id` was **not** provided and we are **not** in 'strict' search mode.
+          #   However, it could be we were in `strict` mode and `external_id` was not provided.
+          # @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
+          # @param strict [Boolean] if should perform a `:soft` or a `:strict` search. `strict` will avoid repeated email addresses.
+          # @return [Entry, nil] the entry we were searching, or `nil` if not found.
           def entry(id: nil, external_id: nil, email: nil, strict: false)
             init_caches
-            pers = nil
-            pers = @by_id[id]&.first if id
-            pers = @by_external_id[external_id&.strip]&.first    if !pers && !external_id.to_s.strip.empty?
-
-            # strict prevents taking existing user for searched person with same email
-            # specially useful if the organisation ensures all have external id (no need for email search)
-            if !pers && (!strict || external_id.to_s.strip.empty?)
-              pers = @by_email[email&.downcase.strip]&.first       if !pers && !email.to_s.strip.empty?
-              pers = @by_external_id[email&.downcase.strip]&.first if !pers && !email.to_s.strip.empty?
-            end
-            pers
+            # normalize values
+            ext_id   = !external_id.to_s.strip.empty? && external_id.strip
+            email    = !email.to_s.strip.empty? && email.downcase.strip
+
+            e   = nil
+            e ||= @by_id[id]&.first
+            e ||= @by_external_id[ext_id]&.first
+            e ||= entry_by_email(email) unless strict && ext_id
+            e
           end
 
           # Search function to find an `entry` based on one of different options
@@ -136,15 +187,33 @@ module Eco
 
           private
 
+          def entry_by_email(email, prevent_multiple_match: false)
+            return nil unless email
+
+            candidates  = @by_email[email] || []
+            return candidates.first if candidates.length == 1
+
+            if prevent_multiple_match && !candidates.empty?
+              msg = "Multiple search results match the criteria."
+              raise MultipleSearchResults.new(msg, candidates: candidates, property: "email")
+            end
+
+            @by_external_id[email]&.first
+          end
+
           def init_caches
             return if @caches_init
-            @by_id          = to_h
-            @by_external_id = to_h('external_id')
-            @by_email       = to_h('email')
+            @by_id          = no_nil_key(to_h)
+            @by_external_id = no_nil_key(to_h('external_id'))
+            @by_email       = no_nil_key(to_h('email'))
             @array_supers   = sort_by_supervisors(@items)
             @caches_init = true
           end
 
+          def no_nil_key(hash)
+            hash.tap {|h| h.delete(nil)}
+          end
+
         end
       end
     end

data/lib/eco/api/common/people/entry_factory.rb

@@ -80,21 +80,21 @@ module Eco
           # @param data [Array<Hash>] data to be parsed. It cannot be used alongside with `file:`
           # @param file [String] absolute or relative path to the input file. It cannot be used alongside with `data:`.
           # @param format [Symbol] it must be used when you use the option `file:` (i.e. `:xml`, `:csv`), as it specifies the format of the input `file:`.
-          # @param encoding [String] optional parameter to read `file:` by expecting certain encoding.
+          # @param options [Hash] further options.
+          # @option options [String] :encoding optional parameter to read `file:` by expecting certain encoding.
+          # @option options [Boolean] :check_headers signals if the `csv` file headers should be expected.
           # @return [Eco::API::Common::People::Entries] collection of `Eco::API::Common::People::PersonEntry`.
-          def entries(data: (no_data = true; nil), file: (no_file = true; nil), format: (no_format = true; nil), encoding: nil)
+          def entries(data: (no_data = true; nil), file: (no_file = true; nil), format: (no_format = true; nil), **options)
             fatal("You should at least use data: or file:, but not both") if no_data == no_file
             fatal("You must specify a valid format: (symbol) when you use file.") if file && no_format
             fatal("Format should be a Symbol. Given '#{format}'") if format && !format.is_a?(Symbol)
             fatal("There is no parser/serializer for format ':#{format.to_s}'") unless no_format || @person_parser.defined?(format)
 
-            kargs = {}
-            kargs.merge!(content:  data)     unless no_data
-            kargs.merge!(file:     file)     unless no_file
-            kargs.merge!(format:   format)   unless no_format
-            kargs.merge!(encoding: encoding) if encoding
+            options.merge!(content:  data)     unless no_data
+            options.merge!(file:     file)     unless no_file
+            options.merge!(format:   format)   unless no_format
 
-            Entries.new(to_array_of_hashes(**kargs), klass: PersonEntry, factory: self)
+            Entries.new(to_array_of_hashes(**options), klass: PersonEntry, factory: self)
           end
 
           def to_array_of_hashes(**kargs)
@@ -118,7 +118,8 @@ module Eco
               logger.error("Input data as 'Hash' not supported. Expecting 'Enumerable' or 'String'")
               exit(1)
             when String
-              to_array_of_hashes(content: person_parser.parse(format, content))
+              deps = {check_headers: true} if kargs[:check_headers]
+              to_array_of_hashes(content: person_parser.parse(format, content, deps: deps || {}))
             when Enumerable
               sample = content.to_a.first
               case sample
@@ -164,7 +165,7 @@ module Eco
 
             run = true
             if Eco::API::Common::Session::FileManager.file_exists?(file)
-              prompt_user("The file '#{file}' already exists. Do you want to overwrite it? (Y/n):", default: "Y") do |response|
+              prompt_user("Do you want to overwrite it? (Y/n):", explanation: "The file '#{file}' already exists.", default: "Y") do |response|
                 run = (response == "") || reponse.upcase.start_with?("Y")
               end
             end

data/lib/eco/api/common/people/person_attribute_parser.rb

@@ -6,6 +6,14 @@ module Eco
         # Class to define a parser/serializer.
         class PersonAttributeParser < Eco::Language::Models::ParserSerializer
 
+          # @note
+          #   - This was introduced at a later stage and might not be available for certain org-parsers configs
+          # @return [RequiredAttrs]
+          def required_attrs
+            @required_attrs ||= @dependencies[:required_attrs]
+            #@required_attrs ||= RequiredAttrs.new(attr, :unkown, [attr])
+          end
+
           # @see Eco::Language::Models::ParserSerializer#def_parser
           # @note
           #  - additionally, you can declare a callback `active:` to determine if when the

data/lib/eco/api/common/people/person_entry.rb

@@ -188,7 +188,7 @@ module Eco
           # @param person [Ecoportal::API::V1::Person] the person we want to set the core values to.
           # @param exclude [String, Array<String>] core attributes that should not be set/changed to the person.
           def set_core(person, exclude: nil)
-            scoped_attrs = @emap.core_attrs - into_a(exclude)
+            scoped_attrs = @emap.core_attrs(@final_entry) - into_a(exclude)
             @final_entry.slice(*scoped_attrs).each do |attr, value|
               begin
                 set_part(person, attr, value)
@@ -210,7 +210,7 @@ module Eco
           # @param exclude [String, Array<String>] account properties that should not be set/changed to the person.
           def set_account(person, exclude: nil)
             person.account = {} if !person.account
-            scoped_attrs = @emap.account_attrs - into_a(exclude)
+            scoped_attrs = @emap.account_attrs(@final_entry) - into_a(exclude)
             @final_entry.slice(*scoped_attrs).each do |attr, value|
               set_part(person.account, attr, value)
             end
@@ -224,7 +224,7 @@ module Eco
           # @param exclude [String, Array<String>] schema field attributes that should not be set/changed to the person.
           def set_details(person, exclude: nil)
             person.add_details(@person_parser.schema) if !person.details || !person.details.schema_id
-            scoped_attrs = @emap.details_attrs - into_a(exclude)
+            scoped_attrs = @emap.details_attrs(@final_entry) - into_a(exclude)
             @final_entry.slice(*scoped_attrs).each do |attr, value|
               set_part(person.details, attr, value)
             end
@@ -326,12 +326,13 @@ module Eco
           # @param internal_entry [Hash] the entry with the **internal** _attribute_ names and values but the **external** types.
           # @return [Hash] the `parsed entry` with the **internal** final attributes names, values and types.
           def _final_parsing(internal_entry)
-            core_account      = @emap.account_attrs + @emap.core_attrs
-            core_account_hash = internal_entry.slice(*core_account).each_with_object({}) do |(attr, value), hash|
+            core_account_attrs = @emap.account_attrs(internal_entry) + @emap.core_attrs(internal_entry)
+            core_account_hash  = internal_entry.slice(*core_account_attrs).each_with_object({}) do |(attr, value), hash|
               hash[attr]  = _parse_type(attr, value)
             end
 
-            details_hash      = internal_entry.slice(*@emap.details_attrs).each_with_object({}) do |(attr, value), hash|
+            details_attrs     = @emap.details_attrs(internal_entry)
+            details_hash      = internal_entry.slice(*details_attrs).each_with_object({}) do |(attr, value), hash|
               hash[attr] = _parse_type(attr, value, schema: @person_parser.schema)
             end
 

data/lib/eco/api/common/people/person_entry_attribute_mapper.rb

@@ -3,18 +3,11 @@ module Eco
     module Common
       module People
 
-        # @attr_reader core_attrs [Array<String>] core attributes that are present in the person entry.
-        # @attr_reader details_attrs [Array<String>] schema details attributes that are present in the person entry.
-        # @attr_reader account_attrs [Array<String>] account attributes that are present in the person entry.
-        # @attr_reader all_model_attrs [Array<String>] all the attrs that are present in the person entry.
-        # @attr_reader internal_attrs [Array<String>] all the internally named attributes that the person entry has.
-        # @attr_reader aliased_attrs [Array<String>] only those internal attributes present in the person entry that have an internal/external name mapping.
         # @attr_reader direct_attrs [Array<String>] only those internal attributes present in the person entry that do **not** have an internal/external name mapping.
         class PersonEntryAttributeMapper
           @@cached_warnings = {}
 
-          attr_reader :core_attrs, :details_attrs, :account_attrs, :all_model_attrs
-          attr_reader :internal_attrs, :aliased_attrs, :direct_attrs
+          attr_reader :aliased_attrs, :direct_attrs
 
           # Helper class tied to `PersonEntry` that allows to track which attributes of a person entry are present
           # and how they should be mapped between internal and external names if applicable.
@@ -38,17 +31,64 @@ module Eco
 
             if parsing?
               @external_entry   = data
-              init_attr_trackers
             else  # SERIALIZING
               @person          = data
-              @internal_attrs  = @person_parser.all_model_attrs
-              @aliased_attrs   = @attr_map.list(:internal)
             end
+          end
 
-            @core_attrs    = @person_parser.target_attrs_core(@internal_attrs)
-            @details_attrs = @person_parser.target_attrs_details(@internal_attrs)
-            @account_attrs = @person_parser.target_attrs_account(@internal_attrs)
-            @all_model_attrs = @core_attrs | @account_attrs | @details_attrs
+          # @return [Array<String>] only those internal attributes present in the person entry that have an internal/external name mapping.
+          def aliased_attrs
+            return @aliased_attrs unless !@aliased_attrs
+            if parsing?
+              init_attr_trackers
+            else
+              @aliased_attrs = @attr_map.list(:internal)
+            end
+            @aliased_attrs
+          end
+
+          # @return [Array<String>] all the internally named attributes that the person entry has.
+          def internal_attrs(data = nil)
+            return @internal_attrs unless data || !@internal_attrs
+            if parsing?
+              init_attr_trackers unless @internal_attrs
+              if data
+                return data.keys & @person_parser.all_model_attrs
+              end
+            else
+              @internal_attrs = @person_parser.all_model_attrs
+            end
+            @internal_attrs
+          end
+
+
+          # @return [Array<String>] all the attrs that are present in the person entry.
+          def all_model_attrs(data = nil)
+            core_attrs(data) | account_attrs(data) | details_attrs(data)
+          end
+
+          # @return [Array<String>] core attributes that are present in the person entry.
+          def core_attrs(data = nil)
+            return @core_attrs unless data || !@core_attrs
+            @person_parser.target_attrs_core(internal_attrs(data)).tap do |core_attrs|
+              @core_attrs ||= core_attrs
+            end
+          end
+
+          # @return [Array<String>] schema details attributes that are present in the person entry.
+          def details_attrs(data = nil)
+            return @details_attrs unless data || !@core_attrs
+            @person_parser.target_attrs_details(internal_attrs(data)).tap do |details_attrs|
+              @details_attrs ||= details_attrs
+            end
+          end
+
+          # @return [Array<String>] account attributes that are present in the person entry.
+          def account_attrs(data = nil)
+            return @account_attrs unless data || !@account_attrs
+            @person_parser.target_attrs_account(internal_attrs(data)).tap do |account_attrs|
+              @account_attrs ||= account_attrs
+            end
           end
 
           # To know if currently the object is in parse or serialize mode.
@@ -151,7 +191,6 @@ module Eco
             def_unlinked      = @person_parser.undefined_model_attrs.select { |attr| !to_external(attr) }
             # (def) those with parser or alias:
             def_linked        = def_all_attrs - def_unlinked
-
             # (data) data attributes (actual attributes of the entry)
             data_attrs        = attributes(@external_entry)
             # (data) attributes of the data that come directly as internal attribute names

data/lib/eco/api/common/people/person_factory.rb

@@ -10,7 +10,7 @@ module Eco
 
           attr_reader :schema, :schema_attrs
 
-          def initialize(person: {}, schema: {}, account: {}, modifier: Common::People::PersonModifier.new)
+          def initialize(person: nil, schema: {}, account: {}, modifier: Common::People::PersonModifier.new)
             @modifier = Common::People::PersonModifier.new(modifier)
             @person  = person
             @account = account
@@ -77,7 +77,9 @@ module Eco
             when Hash
               JSON.parse(person.to_json)
             else
-              {}
+              {
+                "subordinates" => 0
+              }
             end
           end
 

data/lib/eco/api/common/people/person_parser.rb

@@ -59,9 +59,15 @@ module Eco
 
           # @!group Scopping attributes (identifying, presence & active)
 
+          # @return [Array<Eco::API::Common::Loaders::Parser::RequiredAttrs>]
+          def required_attrs
+            @parsers.values_at(*all_attrs(include_defined_parsers: true)).compact.map(&:required_attrs).compact
+          end
+
           # All the internal name attributes, including _core_, _account_ and _details_.
           def all_attrs(include_defined_parsers: false)
-            all_model_attrs | defined_model_attrs
+            return all_model_attrs | defined_model_attrs if include_defined_parsers
+            all_model_attrs
           end
 
           # Scopes `source_attrs` using the _**core** attributes_.

data/lib/eco/api/common/people/supervisor_helpers.rb

@@ -15,7 +15,7 @@ module Eco
             # Reorders as follows:
             #   1. supervisors, people with no supervisor or where their supervisor not present
             #   2. subordinates
-            # @return [Array<Entry>] `values` sorted by supervisors/subordinates
+            # @return [Array<PersonEntry>] `values` sorted by supervisors/subordinates
             def sort_by_supervisors(values, supervisors_first: true)
               raise "Expected non hash Enumerable. Given: #{values.class}" if values.is_a?(Hash)
               return [] unless values && values.is_a?(Enumerable)

data/lib/eco/api/common/version_patches/ecoportal_api/external_person.rb

@@ -5,14 +5,6 @@ module Ecoportal
       class Person
         attr_accessor :entry
 
-        def reset_details!
-          doc["details"] = JSON.parse(original_doc["details"])
-        end
-
-        def consolidate_details!
-          original_doc["details"] = JSON.parse(doc["details"])
-        end
-
         def identify(section = :person)
           if entry && section == :entry
             entry.to_s(:identify)

data/lib/eco/api/common/version_patches/ecoportal_api/internal_person.rb

@@ -3,14 +3,6 @@ module Ecoportal
     class Internal
       class Person
 
-        def reset_account!
-          doc["account"] = JSON.parse(original_doc["account"])
-        end
-
-        def consolidate_account!
-          original_doc["account"] = JSON.parse(doc["account"])
-        end
-
         def new?(doc = :initial)
           ref_doc = (doc == :original) ? original_doc : initial_doc
           !ref_doc["details"] && !ref_doc["account"]

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

@@ -12,9 +12,11 @@ module Eco
         unless options.dig(:exclude, :core) && !person.new?
           micro.set_core(entry, person, options)
           if entry.supervisor_id?
-            micro.set_supervisor(entry.supervisor_id, person, people, options) do |unkown_id|
+            micro.set_supervisor(person, entry.supervisor_id, people, options) do |unknown_id|
               # delay setting supervisor if does not exit
-              supers_job.add(person) {|person| person.supervisor_id = unkown_id}
+              supers_job.add(person) do |person|
+                micro.set_supervisor(person, unknown_id, people, options)
+              end
             end
           end
         end

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

@@ -1,22 +1,27 @@
 module Eco
   module API
     class MicroCases
-      # 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`.
+      # Unique access point to set the `supervisor_id` value on a 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 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(sup_id, person, people, options)
+      def set_supervisor(person, sup_id, people, options)
         unless options.dig(:exclude, :core) || options.dig(:exclude, :supervisor)
-          micro.with_supervisor(sup_id, people) do |supervisor|
+          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
-            elsif supervisor
-              person.supervisor_id = supervisor.id
+              descrease_subordinates(cur_super)
+            elsif new_super && id = new_super.id
+              person.supervisor_id = id
+              descrease_subordinates(cur_super)
+              increase_subordinates(new_super)
             elsif !block_given?
+              descrease_subordinates(cur_super)
               person.supervisor_id = sup_id
             else
               yield(sup_id) if block_given?
@@ -25,6 +30,22 @@ module Eco
         end
       end
 
+      private
+
+      def descrease_subordinates(person, by = 1)
+        if person.is_a?(Ecoportal::API::V1::Person)
+          person.subordinates -= by
+          #person.subordinates  = 0 if person.subordinates < 0
+        end
+      end
+
+      def increase_subordinates(person, by = 1)
+        if person.is_a?(Ecoportal::API::V1::Person)
+          #person.subordinates  = 0 if person.subordinates < 0
+          person.subordinates += by
+        end
+      end
+
     end
   end
 end