eco-helpers 2.0.18 → 2.0.19

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 678fc1c610a5aafd8321a74367a6aaca67aa70bf159f638209b45da0361bb575
-  data.tar.gz: 280a74a3a3877c5d58bfbe84d0f6a8f8b6f8eda5c68f376fea87522b03a59e42
+  metadata.gz: 14260868c76936513a93d4d104eacebbd11e47ed05806d4102ee76196a300d2b
+  data.tar.gz: 35784d03a18f89d2ce8bf5c4105e0eaa647dd10b4e1fee03897319d9ad838760
 SHA512:
-  metadata.gz: 30c74c7aa8b7f59a4610cb4da804714a165a095d6280b756dcec17df37a81f2b5438a7178cc279750e5f97a43ae6d0041e464d9ed7965af39c39fc71ce4efc99
-  data.tar.gz: 1abe7f74b0a0452565c1add7778086030372f63912fe2c6279a2d40eb9f908d07746421507241d4905bbdf546e944899fa0f63fa3e3fe086caf1663c83a2624d
+  metadata.gz: 514d71e93bfa4fb854d9062be03306e154a4dfd184256ab03da30e2bf4bb2a45fb305efd5e2206821e522dc7cc0bfbc69e75285e3c6292dca78f359bd166f52a
+  data.tar.gz: c99a424905916cef61333c18bb31726e90fb9759a4a1b747b72ab123f4bc09ecc6962205a966b3ea46aa1f0a4cc3dd7f72a8c53829cc764a7993d64ad45495bf

data/CHANGELOG.md

@@ -1,13 +1,26 @@
 # Change Log
 All notable changes to this project will be documented in this file.
 
+## [2.0.19] - 2021-05-xx
+
+### Added
+  - Better error message for people searches & **offer** to select among the candidates:
+    - `Eco::API::Organization::People::MultipleSearchResults`, triggered from `Eco::API::Organization::People#find`
+    - `Eco::API::MicroCases#with_each` will offer the selection of candidates
+
+### Changed
+  - **renamed** and repurposed `Eco::API::Organization::PeopleAnalytics` to `PeopleSimilarity`
+
+### Fixed
+  - `Eco::Data::FuzzyMatch` adjustments for configuration propagation + some fixes
+  - Command option `-entries-from` can still be useful when used to obtain `-get-partial` of people base for `:export` use cases !!
+
 ## [2.0.18] - 2021-05-25
 
 ### Added
   - **`-one-off`** option to not having to type the `-api-key` every time you launch one-off scripts
     - `-api-key` will store the key to the `./.env_one_off` file (supports update and multi-environment)
 
-### Changed
 ### Fixed
   - patched `Exception#patch_full_message` to do not enter into a cyclic error rescue
   - also rescue on `workflow.rescue`

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

@@ -2,6 +2,10 @@ module Eco
   module API
     module Common
       module People
+        # TODO: EntryFactory should suppport multiple schemas itself
+        # => currently, it's through session.entry_factory(schema: id), but this is wrong
+        # => This way, Entries and PersonEntry will be able to refer to attr_map and person_parser linked to schema_id
+        # => "schema_id" should be an optional column in the input file, or parsable via a custom parser to scope the schema
         # Helper factory class to generate entries (input entries).
         # @attr_reader schema [Ecoportal::API::V1::PersonSchema] person schema to be used in this entry factory
         class EntryFactory < Eco::API::Common::Session::BaseSession
@@ -12,7 +16,7 @@ module Eco
           # @param schema [Ecoportal::API::V1::PersonSchema] schema of person details that the parser will be based upon.
           # @param person_parser [nil, Eco::API::Common::People::PersonParser] set of attribute, type and format parsers/serializers.
           # @param attr_map [nil, Eco::Data::Mapper] attribute names mapper to translate external names into internal ones and _vice versa_.
-          def initialize(e, schema:, person_parser: nil, attr_map: nil)
+          def initialize(e, schema:, person_parser: nil, default_parser: nil, attr_map: nil)
             fatal "Constructor needs a PersonSchema. Given: #{schema}" if !schema.is_a?(Ecoportal::API::V1::PersonSchema)
             fatal "Expecting PersonParser. Given: #{person_parser}"    if person_parser && !person_parser.is_a?(Eco::API::Common::People::PersonParser)
             fatal "Expecting Mapper object. Given: #{fields_mapper}"   if attr_map && !attr_map.is_a?(Eco::Data::Mapper)
@@ -22,14 +26,25 @@ module Eco
             @source_person_parser = person_parser
 
             # load default parser + custom parsers
-            base_parser = Eco::API::Common::People::DefaultParsers.new(schema: @schema).merge(@source_person_parser)
+            @default_parser = default_parser&.new(schema: @schema) || Eco::API::Common::People::DefaultParsers.new(schema: @schema)
+            base_parser = @default_parser.merge(@source_person_parser)
             # new parser with linked schema
             @person_parser = @source_person_parser.new(schema: @schema).merge(base_parser)
             @person_parser_patch_version = @source_person_parser.patch_version
-
             @attr_map = attr_map
           end
 
+          def newFactory(schema: nil)
+            self.class.new(
+              environment,
+              schema: schema,
+              person_parser: @source_person_parser,
+              default_parser: @default_parser,
+              attr_map: @attr_map
+            )
+          end
+
+
           # provides with a Eco::API::Common::People::PersonParser object (collection of attribute parsers)
           # @note if the custom person parser has changed, it updates the copy of this EntryFactory instance
           # @return [Eco::API::Common::People::PersonParser] set of attribute, type and format parsers/serializers.
@@ -43,7 +58,7 @@ module Eco
 
           # key method to generate objects of `PersonEntry` that share dependencies via this `EntryFactory` environment.
           # @note this method is necessary to make the factory object work as a if it was a class `PersonEntry` you can call `new` on.
-          # @param data [Array<Hash>] data to be parsed. The external hashed entry.
+          # @param data [Hash, Person] data to be parsed/serialized. Parsed: the external hashed entry. Serialized: a Person object.
           # @return [Eco::API::Common::People::PersonEntry]
           def new(data, dependencies: {})
             PersonEntry.new(
@@ -104,7 +119,7 @@ module Eco
           # @param format [Symbol] it specifies the format of the output `file:` (i.e. `:xml`, `:csv`). There must be a parser/serializer defined for it.
           # @param encoding [String] optional parameter to geneate `file:` content by unsing certain encoding.
           # @return [Void].
-          def export(data:, file: "export", format: :csv, encoding: "utf-8")
+          def export(data:, file: "export", format: :csv, encoding: "utf-8", internal_names: false)
             fatal("data: Expected Eco::API::Organization::People object. Given: #{data.class}") unless data.is_a?(Eco::API::Organization::People)
             fatal("A file should be specified.") unless !file.to_s.strip.empty?
             fatal("Format should be a Symbol. Given '#{format}'") if format && !format.is_a?(Symbol)
@@ -112,16 +127,18 @@ module Eco
 
             run = true
             if Eco::API::Common::Session::FileManager.file_exists?(file)
-              print "The file '#{file}' already exists. Do you want to overwrite it? (Y/n): "
-              res = STDIN.gets.strip
-              run = ["y", "Y", ""].include?(res)
+              prompt_user("The file '#{file}' already exists. Do you want to overwrite it? (Y/n):", default: "Y") do |response|
+                run = (response == "") || reponse.upcase.start_with?("Y")
+              end
             end
 
             if run
               deps = {"supervisor_id" => {people: data}}
 
               data_entries = data.map do |person|
-                self.new(person, dependencies: deps).external_entry
+                self.new(person, dependencies: deps).yield_self do |entry|
+                  internal_names ? entry.mapped_entry : entry.external_entry
+                end
               end
 
               File.open(file, "w", enconding: encoding) do |fd|

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

@@ -216,6 +216,7 @@ module Eco
             end
           end
 
+          # TO DO: use person.details.schema_id to switch @emap and @person_parser (or just crash if they don't match?)
           # Setter to fill in all the schema `details` fields of the `Person` that are present in the `Entry`.
           # @note it only sets those details properties defined in the entry.
           #  Meaning that if an details property is not present in the entry, this will not be set on the target person.

data/lib/eco/api/common/session.rb

@@ -13,4 +13,5 @@ require_relative 'session/sftp'
 require_relative 'session/s3_uploader'
 require_relative 'session/file_manager'
 require_relative 'session/environment'
+require_relative 'session/helpers'
 require_relative 'session/base_session'

data/lib/eco/api/common/session/base_session.rb

@@ -11,6 +11,8 @@ module Eco
           attr_reader  :api, :file_manager, :logger
           alias_method :fm, :file_manager
 
+          include Session::Helpers
+          
           def initialize(e)
             raise "Expected object Eco::API::Common::Session::Environment. Given: #{e.class}" unless e.is_a?(Environment)
             self.environment = e

data/lib/eco/api/common/session/helpers.rb

@@ -0,0 +1,30 @@
+require_relative 'helpers/prompt_user'
+
+module Eco
+  module API
+    module Common
+      module Session
+        module Helpers
+
+          class << self
+            def included(base)
+              base.send(:include, InstanceMethods)
+              base.extend(ClassMethods)
+            end
+          end
+
+
+          module ClassMethods
+
+          end
+
+          module InstanceMethods
+            include Helpers::PromptUser
+            
+          end
+
+        end
+      end
+    end
+  end
+end

data/lib/eco/api/common/session/helpers/prompt_user.rb

@@ -0,0 +1,34 @@
+require 'timeout'
+module Eco
+  module API
+    module Common
+      module Session
+        module Helpers
+          module PromptUser
+
+            def prompt_user(question, default:, explanation: "", timeout: nil)
+              response = if config.run_mode_remote?
+                          default
+                        else
+                          puts explanation
+                          print "#{question} "
+                          if timeout
+                            begin
+                              Timeout::timeout(timeout) { STDIN.gets.chop }
+                            rescue Timeout::Error
+                              default
+                            end
+                          else
+                            STDIN.gets.chop
+                          end
+                        end
+              return response unless block_given?
+              yield(response)
+            end
+
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -18,7 +18,7 @@ module Ecoportal
             entry.to_s(:identify)
           else
             str_id = id ? "id: '#{id}'; " : ""
-            "#{name}' (#{str_id}ext_id: '#{external_id}'; email: '#{email}')"
+            "'#{name}' (#{str_id}ext_id: '#{external_id}'; email: '#{email}')"
           end
         end
 

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

@@ -11,12 +11,15 @@ module Ecoportal
           original_doc["account"] = JSON.parse(doc["account"])
         end
 
-        def new?
-          !initial_doc["details"] && !initial_doc["account"]
+        def new?(doc = :initial)
+          ref_doc = (doc == :original) ? original_doc : initial_doc
+          !ref_doc["details"] && !ref_doc["account"]
         end
 
-        def account_added?
-          account && !initial_doc["account"]
+        # @return [Boolean] if the account has been added, compared to `doc`
+        def account_added?(doc = :initial)
+          ref_doc = (doc == :original) ? original_doc : initial_doc
+          account && !ref_doc["account"]
         end
 
       end

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

@@ -12,16 +12,77 @@ module Eco
       # @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
+        @_skip_all_multiple_results = false
+        entries.each_with_object([]) do |entry, scoped|
+          begin
+            unless person = people.find(entry, strict: micro.strict_search?(options))
+              person = session.new_person
+            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
+
+          if person
+            person.entry = entry
+            yield(entry, person) if block_given?
+            scoped << person
           end
-          person.entry = entry
-          yield(entry, person) if block_given?
-          person
         end.yield_self {|all_people| people.newFrom all_people.uniq}
       end
 
+      private
+
+      def _with_each_prompt_to_select_user(error, entry: nil, increase_count: true)
+        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.to_s + "\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
+          case
+          when res.start_with?("I")
+            logger.info "Ignoring entry... #{entry.to_s(:identify) if entry}"
+            nil
+          when res.start_with?("A")
+            logger.info "All input entries with this same issue will be ignored for this launch"
+            @_skip_all_multiple_results = true
+            nil
+          when res.start_with?("C")
+            logger.info "Creating new person...#{"for entry #{entry.to_s(:identify)}" if entry}"
+            session.new_person
+          when res.start_with?("B")
+            raise error
+          when res && !res.empty? && (pos = res.to_i rescue nil) && (pos < error.candidates.length)
+            error.candidate(pos).tap do |person|
+              logger.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

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

@@ -15,8 +15,10 @@ module Eco
       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)}")
+          if person.new?
+            if log_starter
+              session.logger.error("This person does not exist: #{entry.to_s(:identify)}")
+            end
             next
           end
           found << person

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

@@ -15,8 +15,10 @@ module Eco
       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)}")
+          if !person.new?
+            if log_present
+              session.logger.error("This person (id: '#{person.id}') already exists: #{entry.to_s(:identify)}")
+            end
             next
           end
           starters << person

data/lib/eco/api/organization.rb

@@ -9,7 +9,7 @@ require_relative 'organization/tag_tree'
 require_relative 'organization/presets_factory'
 require_relative 'organization/preferences'
 require_relative 'organization/people'
-require_relative 'organization/people_analytics'
+require_relative 'organization/people_similarity'
 require_relative 'organization/person_schemas'
 require_relative 'organization/policy_groups'
 require_relative 'organization/login_providers'

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

@@ -2,6 +2,43 @@ module Eco
   module API
     module Organization
       class People <  Eco::Language::Models::Collection
+        # Error class that allows to handle cases where multiple people were found for the same criterion.
+        # @note its main purpose to prevent the creation 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<Person>] the people that match the same search criterion.
+          # @param property [String] the property of the person 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 |person, i|
+              index = with_index     ? "#{i}. " : ""
+              msg   = person.account ? (person.account_added? ? "(new user)" : "(user)") :  "(no account)"
+              "#{index}#{msg} #{person.identify}"
+            end
+          end
+
+          # @return [Person] the `candidate` in the `index` position
+          def candidate(index)
+            candidates[index]
+          end
+
+          private
+
+          def candidates_summary
+            lines = ["The following people have the same '#{property}':"]
+            lines.concat(identify_candidates(with_index: true)).join("\n  ")
+          end
+
+        end
+
         # build the shortcuts of Collection
         attr_presence :account, :details
         attr_collection :id, :external_id, :email, :name, :supervisor_id
@@ -78,34 +115,36 @@ module Eco
         # @!group Searchers
 
         # It searches a person using the parameters given.
+        # @note This is how the search function actually works:
+        #   1. if eP `id` is given, returns the person (if found), otherwise...
+        #   2. if `external_id` is given, returns the person (if found), otherwise...
+        #   3. if `strict` is `false` and `email` is given:
+        #     - if there is only 1 person with that email, returns that person, otherwise...
+        #     - if found but, there are many candidates, it raises MultipleSearchResults error
+        #     - if person `external_id` matches `email`, returns that person
+        # @raise MultipleSearchResults if there are multiple people with the same `email`
+        #   and there's no other criteria to find the person. 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.
+        # @param strict [Boolean] if should perform a `:soft` or a `:strict` search. `strict` will avoid repeated email addresses.
         # @return [Person, nil] the person we were searching, or `nil` if not found.
         def person(id: nil, external_id: nil, email: nil, strict: false)
           init_caches
-          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?)
-            # person still not found and either not strict or no external_id provided
-            pers = @by_users_email[email&.downcase.strip]&.first  if !email.to_s.strip.empty?
-
-            if !pers && !strict && !email.to_s.strip.empty?
-              candidates = @by_non_users_email[email&.downcase.strip] || []
-              raise "Too many non-user candidates (#{candidates.length}) with email '#{email}'" if candidates.length > 1
-              pers = candidates.first
-            end
-
-            pers = @by_external_id[email&.downcase.strip]&.first    if !pers && !email.to_s.strip.empty?
-          end
-
+          # normalize values
+          ext_id   = !external_id.to_s.strip.empty? && external_id.strip
+          email    = !email.to_s.strip.empty? && email.downcase.strip
+
+          pers   = nil
+          pers ||= @by_id[id]&.first
+          pers ||= @by_external_id[ext_id]&.first
+          pers ||= person_by_email(email) unless strict && ext_id
           pers
         end
 
+        # @see Eco::API::Organization::People#person
         def find(object, strict: false)
           id          = attr_value(object, "id")
           external_id = attr_value(object, "external_id")
@@ -190,16 +229,46 @@ module Eco
 
         private
 
+        def person_by_email(email, prevent_duplicates: true)
+          return nil unless email
+
+          candidates  = @by_non_users_email[email] || []
+          email_users = @by_users_email[email]     || []
+
+          if pers = email_users.first
+            return pers if candidates.empty?
+            candidates = [pers] + candidates
+          elsif candidates.length == 1
+            return candidates.first
+          end
+
+          if prevent_duplicates && !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_users_email     = users.to_h('email')
-          @by_non_users_email = non_users.to_h('email')
-          @by_email           = to_h('email')
+          @by_external_id     = no_nil_key(to_h('external_id'))
+          @by_users_email     = no_nil_key(existing_users.to_h('email'))
+          @by_non_users_email = no_nil_key(non_users.to_h('email'))
+          @by_email           = no_nil_key(to_h('email'))
           @caches_init = true
         end
 
+        def existing_users
+          newFrom users.select {|u| !u.account_added?(:original)}
+        end
+
+        def no_nil_key(hash)
+          hash.tap {|h| h.delete(nil)}
+        end
+
+
       end
     end
   end