eco-helpers 2.0.25 → 2.0.26

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 06a58306abadf9b27421583990eb14960f7f30368515481b16aa474de1bc1b08
-  data.tar.gz: 0eef93068fdb31bc6d1949f1022eac325403ac3dbb47c95b593a5b9623655773
+  metadata.gz: 722e1dc695f9d9fae5fbceca8a2269f4836393ee4dc50fc0f850e43fefc88789
+  data.tar.gz: bc34444cdf33bff51895fa5ed6bb7a89b89074e5bd11852c0a1a4f4bf6bcc574
 SHA512:
-  metadata.gz: 80b0d2fc7bedb99deabae6d7d273cb4967eb0022db2e743078a82cace02d4f499fe8ad51ec02b7c5bcef549aac9fb03b0ea7ef5358fb602c65856654c7c20814
-  data.tar.gz: 553e1342f38c244ab57bb259b639d55ddc4a4d5d6f72bd54ed9290111636f4dffb29834f69a5b7d2707ee3d44951fa52efccf81589194f11dfa1a709309ddb77
+  metadata.gz: 9a18aaa7abf012872f21209907909f1c309ddb530586bc9e27d595ace57377c3c4dba2b0a7bacc902e160cf2f51d4171a5de3e0536b6eda4dff7d018307744ca
+  data.tar.gz: efcaa1832677c0cf13d5dfb0ba6a3abaa8bff3fec4e1d2639b2b832358a1e51b849e594da64827bed096eb4f8f03a5664a6a8245c58128acf3478eaf0e94d38a

data/CHANGELOG.md

@@ -1,11 +1,62 @@
 # Change Log
 All notable changes to this project will be documented in this file.
 
-## [2.0.25] - 2021-06-xx
+## [2.0.26] - 2021-06-xx
+
+### Added
+  - `Eco::API::MicroCases#set_supervisor`, tries to keep in sync the `#subordinates` **count** of previous and new supervisor
+  - new **option** `-run-postlaunch` to run post launch cases, even when we run in `dry-run` mode
+    * when in `dry-run` it will **not** reload the people base of the session
+  - new **option** to append **new** entries to the `People` object
+    * **invokable** on **cli** via `-append-starters` (`{people: {append_created: true}}`)
+    * the following use cases include this option:
+      * `Eco::API::UseCases::DefaultCases::UpsertCase`
+      * `Eco::API::UseCases::DefaultCases::HrisCase`
+      * `Eco::API::UseCases::DefaultCases::CreateDetailsWithSupervisorCase`
+      * `Eco::API::UseCases::DefaultCases::CreateDetailsCase`
+      * `Eco::API::UseCases::DefaultCases::CreateCase`
+    * the option involves a new keyed argument `:append_created` in a couple of `MicroCases`
+      * `Eco::API::MicroCases#with_each`: where internally the search is performed against a copy of the `People` object.
+      * `Eco::API::MicroCases#with_each_starter`
+    * when `--help` is invoked option to filter the shown `-options`, `-usecases` and `filters` by a word contained in the option.
+  - **added** `csv` **header checks** for feed files, which entailed some changes:
+    * `Eco::API::Common::Loaders::Parser`
+      - new **subclass** `RequiredAttrs`, creatred when calling `.active_when_all` and `.active_when_any`
+      - **dependency** injection via `.dependencies` as `{required_attrs: RequiredAttrs}`
+    * **added** `Eco::API::Common::People::PersonParser#required_attrs` to offer all the `RequiredAttrs`, where defined
+      - the **new method** `#required_attrs` to expose the injected `RequiredAttrs`
+    * **new** keyed argument `check_headers:` in `Eco::API::Common::People::EntryFactory#entries`
+      - subsequent changes to accommodate the new param in `Eco::API::Session#csv_entries`
+      - `eco/cli/config/default/input` calls using this param to `true`
+    * `Eco::API::Common::People::DefaultParsers::CSVParser`
+      - added option `check_headers` via `dependencies` that enables the headers check
+      - it will now offer detailed warning messages on what can happen with the **missing headers**
+        * it will also list the **unknown header** names
+
+### Changed
+  - `Eco::API::MicroCases#set_supervisor`, the order of the 2 first parameters
+  - `Eco::API::Organization::People`: internally `@by_id` cache Hash included `nil` values => **not** any more.
+  - removed **unused** methods on **patches** for `Ecoportal::API::V1::Person` and `Ecoportal::API::Internal::Person`
+    * specifically `#reset_account!` and `#consolidate_account!` as well as `#reset_details!` and `#consolidate_details!`
+  - internal changes in `Eco::API::Common::People::Entries#entry`
+    * **added** option to trigger `MultipleSearchResults` StandardError when multiple candiates are found.
+    * **removed** `nil` values from the `caches` (the Hashes to optimize the search)
+  - slight structure refactor of `Eco::API::Common::Loaders`
+    * moved base class to subfolder/namespace
+    * decoupled pure `Loader` logics to `Loaders::Base` and use case inheriance chain loader to `Loaders::CaseBase`
+  - `Eco::API::Session::BatchJob` the `post_launch`:
+    * sets the `id` to the `person` if it was **created** successfully
+    * when in `dry-run` it fakes the `id` with a counter
+  - `Eco::API::Common::People::PersonFactory` gets `subordinates` initialized to `0` (when **creating** a `new` person)
+
+### Fixed
+
+
+## [2.0.25] - 2021-06-23
 
 ### Added
   - `Eco::API::UseCases::DefaultCases::HrisCase` validation error to require `-schema-id` command line when there are people in schemas other than the active one
-  
+
 ### Changed
   - `Eco::API::Session::Batch::Job`
     * for backwards compatibility `-include-only-excluded` should bring an options structure compatible with `-include-excluded`
@@ -19,7 +70,6 @@ All notable changes to this project will be documented in this file.
   - `Eco::API::Session::Batch::Job` made **native** `-include-excluded`
     * also added new option `-include-only-excluded` to be able to only target people HRIS excluded
 
-
 ## [2.0.23] - 2021-06-22
 
 ### Added
@@ -51,8 +101,6 @@ All notable changes to this project will be documented in this file.
     * we just kept `roo` and `roo-xls`
   - custom `Error` classes now all inherit from `StandardError` (rather than `Exception`)
 
-
-
 ## [2.0.21] - 2021-06-04
 
 ### Added
@@ -63,7 +111,6 @@ All notable changes to this project will be documented in this file.
 ### Changed
   - `Eco::API::Common::People::EntryFactory` slight **refactor** to boost better support for multiple input formats
 
-
 ## [2.0.20] - 2021-05-31
 
 ### Added

data/lib/eco/api/common.rb

@@ -10,7 +10,6 @@ require_relative 'common/class_helpers'
 require_relative 'common/class_auto_loader'
 require_relative 'common/class_hierarchy'
 require_relative 'common/class_meta_basics'
-require_relative 'common/base_loader'
 require_relative 'common/loaders'
 require_relative 'common/session'
 require_relative 'common/people'

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

@@ -7,6 +7,8 @@ module Eco
   end
 end
 
+require_relative 'loaders/base'
+require_relative 'loaders/case_base'
 require_relative 'loaders/use_case'
 require_relative 'loaders/policy'
 require_relative 'loaders/error_handler'

data/lib/eco/api/common/loaders/base.rb

@@ -0,0 +1,58 @@
+module Eco
+  module API
+    module Common
+      module Loaders
+        class Base
+          extend Eco::API::Common::ClassHelpers
+
+          class << self              
+            # Sort order
+            def <=>(other)
+              created_at <=> other.created_at
+            end
+
+            # If still not set, it sets the `created_at` class timestamp.
+            def set_created_at!
+              @created_at = Time.now unless @created_at
+            end
+
+            # Class creation timestamp, to be able to load them in the order they were declared.
+            def created_at
+              @created_at ||= Time.now
+            end
+          end
+
+          # This method will be called when the BaseLoader is created
+          # @note
+          #   - this method should implement the loading logics for the given `Children` class.
+          def initialize
+            raise "You should implement this method"
+          end
+
+          def name
+            self.class.name
+          end
+
+          private
+
+          def session
+            ASSETS.session
+          end
+
+          def config
+            session.config
+          end
+
+          def logger
+            session.logger
+          end
+
+          def micro
+            session.micro
+          end
+
+        end
+      end
+    end
+  end
+end

data/lib/eco/api/common/loaders/case_base.rb

@@ -0,0 +1,33 @@
+module Eco
+  module API
+    module Common
+      module Loaders
+        class CaseBase < Loaders::Base
+
+          class << self
+            attr_writer :name, :type
+
+            # The name that this case, policy or error handler will have.
+            def name(value = nil)
+              name_only_once! if value
+              set_created_at!
+              return @name ||= self.to_s unless value
+              @name = value
+            end
+
+            # Prevent the same class to be re-opened/re-named
+            def name_only_once!
+              raise "You have already declared #{self} or you are trying to give it a name twice" if @name
+            end
+
+          end
+
+          def name
+            self.class.name
+          end
+
+        end
+      end
+    end
+  end
+end

data/lib/eco/api/common/loaders/error_handler.rb

@@ -2,7 +2,7 @@ module Eco
   module API
     module Common
       module Loaders
-        class ErrorHandler < Eco::API::Common::BaseLoader
+        class ErrorHandler < Eco::API::Common::Loaders::CaseBase
 
           class << self
             attr_writer :error
@@ -17,7 +17,7 @@ module Eco
           end
 
           inheritable_class_vars :error
-          
+
           def initialize(handlers)
             raise "Expected Eco::API::Policies. Given #{handlers.class}" unless handlers.is_a?(Eco::API::Error::Handlers)
             handlers.on(self.error, &self.method(:main))

data/lib/eco/api/common/loaders/parser.rb

@@ -2,7 +2,28 @@ module Eco
   module API
     module Common
       module Loaders
-        class Parser < Eco::API::Common::BaseLoader
+        class Parser < Eco::API::Common::Loaders::CaseBase
+
+          # Helper class to scope what required attributes it depends on
+          class RequiredAttrs < Struct.new(:attr, :type, :attrs)
+            def active?(*input_attrs)
+              missing(*input_attrs).empty?
+            end
+
+            def dependant?(attr)
+              attrs.include?(attr)
+            end
+
+            def missing(*input_attrs)
+              return [] if input_attrs.include?(attr)
+              match = input_attrs & attrs
+              miss  = attrs - match
+              return []    if miss.empty?
+              return attrs if match.empty?
+              return miss  if type == :all
+              []
+            end
+          end
 
           class << self
             attr_reader :active_when
@@ -19,12 +40,14 @@ module Eco
               @attribute = value
             end
 
-            # TODO: it migh rather merge?
             # Some parsers require dependencies to do their job.
-            def dependencies(value = nil)
+            def dependencies(**value)
               @dependencies ||= {}
-              return @dependencies unless value
-              @dependencies = value
+              return @dependencies.merge({
+                required_attrs: @active_when_attrs
+              }) unless !value.empty?
+              raise "Expected Hash. Given: '#{value.class}'" unless value.is_a?(Hash)
+              @dependencies.merge!(value)
             end
 
             # Define or get the `phase` that the `parser` kicks in.
@@ -47,6 +70,7 @@ module Eco
 
             # Helper to build the `active_when` condition.
             def active_when_any(*attrs)
+              @active_when_attrs = RequiredAttrs.new(attribute, :any, attrs)
               @active_when = Proc.new do |source_data|
                 keys = data_keys(source_data)
                 attrs.any? {|key| keys.include?(key)}
@@ -55,6 +79,7 @@ module Eco
 
             # Helper to build the `active_when` condition.
             def active_when_all(*attrs)
+              @active_when_attrs = RequiredAttrs.new(attribute, :all, attrs)
               @active_when = Proc.new do |source_data|
                 keys = data_keys(source_data)
                 attrs.all? {|key| keys.include?(key)}

data/lib/eco/api/common/loaders/policy.rb

@@ -2,7 +2,7 @@ module Eco
   module API
     module Common
       module Loaders
-        class Policy < Eco::API::Common::BaseLoader
+        class Policy < Eco::API::Common::Loaders::CaseBase
 
           def initialize(policies)
             raise "Expected Eco::API::Policies. Given #{policies.class}" unless policies.is_a?(Eco::API::Policies)

data/lib/eco/api/common/loaders/use_case.rb

@@ -2,7 +2,7 @@ module Eco
   module API
     module Common
       module Loaders
-        class UseCase < Eco::API::Common::BaseLoader
+        class UseCase < Eco::API::Common::Loaders::CaseBase
 
           class << self
             # @return [Symbol] the `type` of usecase (i.e. `:sync`, `:transform`, `:import`, `:other`)

data/lib/eco/api/common/people/default_parsers/csv_parser.rb

@@ -2,7 +2,9 @@ class Eco::API::Common::People::DefaultParsers::CSVParser < Eco::API::Common::Lo
   attribute :csv
 
   def parser(data, deps)
-    Eco::CSV.parse(data, headers: true, skip_blanks: true).each_with_object([]) do |row, arr_hash|
+    Eco::CSV.parse(data, headers: true, skip_blanks: true).tap do |table|
+      check_headers(table) if deps[:check_headers]
+    end.each_with_object([]) do |row, arr_hash|
       row_hash = row.headers.uniq.each_with_object({}) do |attr, hash|
         next if attr.to_s.strip.empty?
         hash[attr.strip] = parse_string(row[attr])
@@ -36,4 +38,94 @@ class Eco::API::Common::People::DefaultParsers::CSVParser < Eco::API::Common::Lo
     ["NULL"].any? {|token| str == token}
   end
 
+  def check_headers(table)
+    headers = table.headers
+    missing = missing_headers(headers)
+    unknown = unknown_headers(headers)
+    unless missing.empty? && unknown.empty?
+      msg  = "Detected possible HEADER ISSUES !!!\n"
+      msg << "There might be Missing or Wrong HEADER names in the CSV file:\n"
+      msg << "  * UNKNOWN (or not used?): #{unknown}\n" unless unknown.empty?
+      msg << "  * MISSING DIRECT: #{missing[:direct]}\n" unless (missing[:direct] || []).empty?
+      unless (data =  missing[:indirect] || []).empty?
+        msg << "  * MISSING INDIRECT:\n"
+        data.each do |ext, info|
+          msg <<  "    - '#{ext}' => "
+          msg << (info[:attrs] || {}).map do |status, attrs|
+            if status == :inactive
+              "makes inactive: #{attrs}"
+            elsif status == :active
+              "there could be missing info in: #{attrs}"
+            end
+          end.compact.join("; ") + "\n"
+        end
+      end
+      logger.warn(msg)
+      sleep(2)
+    end
+  end
+
+  def unknown_headers(headers)
+    (headers - known_headers) - all_internal_attrs
+  end
+
+  def missing_headers(headers)
+    hint = headers & all_internal_attrs
+    hext = headers - hint
+    int_head = hint + hext.map {|e| fields_mapper.to_internal(e)}.compact
+    known_as_int = known_headers.select do |e|
+      i = fields_mapper.to_internal(e)
+      int_head.include?(i)
+    end
+    ext  = headers.select do |e|
+      i = fields_mapper.to_internal(e)
+      int_head.include?(i)
+    end
+    ext_present = known_as_int | ext
+    ext_miss    = known_headers - ext_present
+    #int_miss  = ext_miss.map {|ext| fields_mapper.to_internal(ext)}
+    ext_miss.each_with_object({}) do |ext, missing|
+      next unless int = fields_mapper.to_internal(ext)
+      if all_internal_attrs.include?(int)
+        missing[:direct] ||= []
+        missing[:direct] << ext
+      end
+      related_attrs_requirements = required_attrs.values.select do |req|
+        req.dependant?(int) && !int_head.include?(req.attr)
+      end
+      next if related_attrs_requirements.empty?
+      missing[:indirect] ||= {}
+      data = missing[:indirect][ext] = {}
+      data[:int]   = int
+      data[:attrs] = {}
+      related_attrs_requirements.each_with_object(data[:attrs]) do |req, attrs|
+        status = req.active?(*int_head) ? :active : :inactive
+        attrs[status] ||= []
+        attrs[status] << req.attr
+      end
+    end
+  end
+
+  def known_headers
+    @known_headers ||= fields_mapper.list(:external).compact
+  end
+
+  def fields_mapper
+    session.fields_mapper
+  end
+
+  def required_attrs
+    @required_attrs ||= person_parser.required_attrs.each_with_object({}) do |ra, out|
+      out[ra.attr] = ra
+    end
+  end
+
+  def all_internal_attrs
+    person_parser.all_attrs(include_defined_parsers: true)
+  end
+
+  def person_parser
+    session.entry_factory.person_parser
+  end
+
 end

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