eco-helpers 1.4.0 → 1.5.2

data/lib/eco/api/custom/use_case.rb

@@ -0,0 +1,16 @@
+# Helper class to create a custom `UseCase`
+# @example Example of usage:
+#  class Custom::UseCase::Sync < Eco::API::Custom::UseCase
+#    name "custom-case"
+#    type :sync
+#
+#    def main(entries, people, session, options, usecase)
+#      update   = session.new_job("main", "update", :update, usecase)
+#      session.micro.with_each(entries, people, options) do |entry, person|
+#        # update some data in person using data from entry
+#      end
+#    end
+#
+#  end
+class Eco::API::Custom::UseCase < Eco::API::Common::Loaders::UseCase
+end

data/lib/eco/api/error.rb

@@ -13,6 +13,7 @@ module Eco
       @match  = /.*/
       #RxValidId = /[a-f0-9]{24}/
 
+
       class Unclassified < Eco::API::Error
         @str_error = "Unclassified error message"
         @match     = /.*/

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

@@ -2,12 +2,14 @@ module Eco
   module API
     class Error
       class Handlers < Eco::API::UseCases
+        autoloads_children_of "Eco::API::Common::Loaders::ErrorHandler"
+        autoload_namespace_ignore "Eco::API"
 
-        def add(handler)
-          raise "Expected Eco::API::Error::Handler object. Given: #{policy}" unless handler.is_a?(Eco::API::Error::Handler)
-          super(handler)
+        def define(*args)
+          raise "Missusage. You should use 'on' method instead"
         end
 
+        # @param klass_err [Eco::API::Error] the specific error class that triggers this handler.
         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
@@ -16,6 +18,11 @@ module Eco
           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
+
       end
     end
   end

data/lib/eco/api/microcases.rb

@@ -0,0 +1,35 @@
+module Eco
+  module API
+    class MicroCases < Eco::API::Common::Session::BaseSession
+
+      def micro
+        self
+      end
+
+    end
+  end
+end
+
+require_relative 'microcases/account_excluded'
+require_relative 'microcases/append_usergroups'
+require_relative 'microcases/core_excluded'
+require_relative 'microcases/fix_default_group'
+require_relative 'microcases/fix_filter_tags'
+require_relative 'microcases/people_cache'
+require_relative 'microcases/people_load'
+require_relative 'microcases/people_refresh'
+require_relative 'microcases/people_search'
+require_relative 'microcases/refresh_abilities'
+require_relative 'microcases/set_account'
+require_relative 'microcases/set_core_with_supervisor'
+require_relative 'microcases/set_core'
+require_relative 'microcases/refresh_default_tag'
+require_relative 'microcases/set_supervisor'
+require_relative 'microcases/strict_search'
+require_relative 'microcases/s3upload_targets'
+require_relative 'microcases/with_each'
+require_relative 'microcases/with_each_leaver'
+require_relative 'microcases/with_each_present'
+require_relative 'microcases/with_each_starter'
+require_relative 'microcases/with_each_subordinate'
+require_relative 'microcases/with_supervisor'

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

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

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

@@ -0,0 +1,19 @@
+module Eco
+  module API
+    class MicroCases
+      # It preserves the usergroups of `person` and appends those defined in `policy_group_ids` of the `entry`
+      # @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 append_usergroups(entry, person, options)
+        unless options.dig(:exclude, :account)
+          if person.account
+            person.account.policy_group_ids |= entry.policy_group_ids
+            micro.refresh_abilities(person, options)
+          end
+        end
+      end
+
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+module Eco
+  module API
+    class MicroCases
+      # @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|
+          unless person.new?
+            exclusions = ["name", "external_id", "email", "filter_tags"].select do |attr|
+              options.dig(:exclude, attr.to_sym)
+            end
+            core_excluded.concat(exclusions)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,34 @@
+module Eco
+  module API
+    class MicroCases
+      # 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)
+        unless options.dig(:exclude, :account)
+          unless 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
+        end
+      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

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

@@ -0,0 +1,42 @@
+module Eco
+  module API
+    class MicroCases
+      # Helper that makes sure the **custom `tags`** are preserved.
+      # @note
+      #   - this feature is essential to preserve custom `tags` in users that have register tags.
+      #   - for this to work out, it requires a `tagtree` to be defined.
+      # @param person [Ecoportal::API::V1::Person] the person we want to update, carrying the changes already done.
+      # @param options [Hash] the options.
+      # @option options [Hash<Symbol, Object>] :filter_tags options around `filter_tags`.
+      #   * `:preserve_custom` (Boolean) [true] indicates if original tags that are not in the tree should be added/preserved.
+      #   * `:add_custom` (Boolean) [true] indicates if target tags that are not in the tree should be really added.
+      def fix_filter_tags(person, options)
+        if session.tagtree
+          unless !person.new? && (options.dig(:exclude, :core) || options.dig(:exclude, :filter_tags))
+            person.filter_tags = session.tagtree.user_tags(
+              initial:          person.original_doc["filter_tags"] || [],
+              final:            person.filter_tags,
+              preserve_custom:  _fix_filter_tags_preserve_custom?(options),
+              add_custom:       _fix_filter_tags_add_custom?(options)
+            )
+          end
+        end
+      end
+
+      private
+
+      # default `true`
+      def _fix_filter_tags_preserve_custom?(options)
+        key_defined = options.key?(:filter_tags) && options[:filter_tags].key?(:preserve_custom)
+        !key_defined || options.dig(:filter_tags, :preserve_custom)
+      end
+
+      # default `true`
+      def _fix_filter_tags_add_custom?(options)
+        key_defined = options.key?(:filter_tags) && options[:filter_tags].key?(:add_custom)
+        !key_defined || options.dig(:filter_tags, :add_custom)
+      end
+
+    end
+  end
+end

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

@@ -0,0 +1,17 @@
+module Eco
+  module API
+    class MicroCases
+      # Helper to locally cache the people manager.
+      # @param filename [String] the name of the file where the data should be cached.
+      # @return [Eco::API::Organization::People] the `People` object with the data.
+      def people_cache(filename = enviro.config.people.cache)
+        logger.info("Going to get all the people via API")
+        people = session.batch.get_people
+        file   = file_manager.save_json(people, filename, :timestamp)
+        logger.info("#{people.length} people loaded and saved locally to #{file}.")
+        Eco::API::Organization::People.new(people)
+      end
+
+    end
+  end
+end

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

@@ -0,0 +1,59 @@
+module Eco
+  module API
+    class MicroCases
+      # Helper to load `People` that works in different phases:
+      #   1. first tries to get the newest cached file that follows `filename` pattern
+      #     - if not the newest, it tries to find the specific filename
+      #   2. if it succeeds to identif a cached file, it loads it
+      #     - if it fails, it tries to get people from the server
+      # @note
+      #  - `filename` will be relative to the working directory (the one of the session `enviro` set by the user).
+      # @param filename [String] the name of the file where the cached data is to be found.
+      # @param modifier [Array<Symbol>] modifiers to specify how this function should proceed:
+      #   - `:newest` if it should try to find the newest file (pattern alike).
+      #   - `:api` if it should try to get people from the server in case there's no cache.
+      #   - `:file` if it is supposed to load people from a file.
+      #   - `:save` if it is supposed to cache/save the data locally once obtained people from the server (`:api`)
+      # @return [Eco::API::Organization::People] the `People` object with the data.
+      def people_load(filename = enviro.config.people.cache, modifier: [:newest, :api])
+        modifier  = [modifier].flatten
+        load_file = [:file, :newest].any? {|flag| modifier.include?(flag)}
+        people    = case
+                    when filename && load_file
+                      if file = people_load_filename(filename, newest: modifier.include?(:newest))
+                        file_manager.load_json(file).tap do |people|
+                          logger.info("#{people&.length} people loaded from file #{file}") if people.is_a?(Array)
+                        end
+                      else
+                        logger.error("could not find the file #{file_manager.dir.file(filename)}")
+                        exit unless modifier.include?(:api)
+                        people_load(modifier: modifier - [:newest, :file])
+                      end
+                    when modifier.include?(:api)
+                      logger.info("Going to get all the people via API")
+                      session.batch.get_people.tap do |people|
+                        if modifier.include?(:save) && people && people.length > 0
+                          file = file_manager.save_json(people, filename, :timestamp)
+                          logger.info("#{people.length } people saved to file #{file}.")
+                        end
+                      end
+                    end
+        Eco::API::Organization::People.new(people)
+      end
+
+      private
+
+      def people_load_filename(filename, newest: false)
+        if newest
+          # search input file based on pattern (in case the name has a timestamp)
+          file_manager.dir.newest_file(file: filename).tap do |file|
+            logger.info("previous file found: #{file}") if file
+          end
+        else
+          file_manager.dir.file(filename, should_exist: true)
+        end
+      end
+
+    end
+  end
+end

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

@@ -0,0 +1,31 @@
+module Eco
+  module API
+    class MicroCases
+      # Helper to obtain all the elements of `people` anew from the _People Manager_.
+      # @note this helper is normally used to run consecutive usecases, where data needs refresh.
+      # @param people [Eco::API::Organization::People] the people that needs refresh.
+      # @param include_created [Boolean] include people created during this session? (will check `:create` batch jobs).
+      # @return [Eco::API::Organization::People] the `People` object with the data.
+      def people_refresh(people:, include_created: true)
+        ini = people.length
+        if include_created
+          session.job_groups.find_jobs(type: :create).map do |job|
+            people = people.merge(job.people)
+          end
+        end
+
+        created = people.length - ini
+        msg  = "Going to refresh #{people.length} people with server data"
+        msg += " (including #{created} that were created)" if created > 0
+        logger.info(msg)
+        entries = session.batch.get_people(people, silent: true)
+
+        missing = people.length - entries.length
+        logger.error("Missed to obtain #{missing} people during the refresh") if missing > 0
+
+        Eco::API::Organization::People.new(status.people)
+      end
+
+    end
+  end
+end

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

@@ -0,0 +1,65 @@
+module Eco
+  module API
+    class MicroCases
+      # Helper to search/obtain people from `data` against the server (_People Manager_).
+      # @note
+      #   - this helper is normally used to **get partial** part of the people manager.
+      #   - therefore, normally used with _**delta** input files_ (files with only the differences).
+      # @param data [Eco::API::Organization::People, Enumerable<Person>, Enumerable<Hash>] `People` to search against the server.
+      # @param options [Hash] the options.
+      # @param silent [Boolean] `false` if low level search messages should be shown.
+      # @return [Eco::API::Organization::People] the `People` object with the found persons.
+      def people_search(data, options: {}, silent: true)
+        session.logger.info("Going to api get #{data.length} entries...")
+        status = session.batch.search(data, silent: silent)
+        people = Eco::API::Organization::People.new(status.people)
+        session.logger.info("... could get #{people.length} people (out of #{data.length} entries)")
+
+        # get the supervisors of found people (current supervisors)
+        supers = people_search_prepare_supers_request(people)
+        if supers.length > 0
+          session.logger.info("  Going to api get #{supers.length} current supervisors...")
+          status = session.batch.search(supers, silent: silent)
+          people = people.merge(status.people, strict: micro.strict_search?(options))
+        end
+
+        # get the supervisors referred in the input data (future supervisors)
+        supers = people_search_prepare_supers_request(data, people)
+        if supers.length > 0
+          session.logger.info("  Going to api get #{supers.length} supervisors as per entries...")
+          status = session.batch.search(supers, silent: silent)
+          people = people.merge(status.people, strict: micro.strict_search?(options))
+        end
+
+        session.logger.info("Finally got #{people.length} people (out of #{data.length} entries)")
+        people
+      end
+
+      private
+
+      # Prepares a unique request with only the supervisor ids missing in `people`
+      def people_search_prepare_supers_request(data, people = data)
+        data.each_with_object([]) do |entry, request|
+          spr = {"id" => (sup_id = people_search_super_id(entry))}
+          unless !sup_id || request.include?(spr)
+            micro.with_supervisor(sup_id, people) do |supervisor|
+              request.push(spr) unless supervisor
+            end
+          end
+        end
+      end
+
+      # Gets the `supervisor_id` from `value`
+      def people_search_super_id(value)
+        sup_id = if value.respond_to?(:supervisor_id)
+                value.supervisor_id
+              elsif value.is_a?(Hash) && value.key("supervisor_id")
+                value["supervisor_id"]
+              end
+        sup_id = nil if sup_id.to_s.strip.empty?
+        sup_id
+      end
+
+    end
+  end
+end

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

@@ -0,0 +1,19 @@
+module Eco
+  module API
+    class MicroCases
+      # It sets the correct set of abilities based on the usergroups of `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 refresh_abilities(person, options)
+        unless options.dig(:exclude, :account)
+          if person.account
+            unless options.dig(:exclude, :abilities) && !person.new?
+              person.account.permissions_custom = session.new_preset(person)
+            end
+          end
+        end
+      end
+
+    end
+  end
+end

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

@@ -0,0 +1,27 @@
+module Eco
+  module API
+    class MicroCases
+      # When the input data, or `entry`, does not provide the `default_tag`,
+      # it sets the `default_tag` of the user following some criteria
+      # @note it assumes `default_tag` has been already set to `person.account`
+      # @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 refresh_default_tag(entry, person, options)
+        if person.account
+          unless options.dig(:exclude, :account)
+            unless options.dig(:exclude, :filter_tags) || options.dig(:exclude, :default_tag) || entry&.default_tag?
+              if session.tagtree
+                person.account.default_tag = session.tagtree.default_tag(*person.filter_tags)
+              else
+                tags = person.filter_tags || []
+                person.account.default_tag = tags.first unless tags.length > 1
+              end
+            end
+          end
+        end
+      end
+
+    end
+  end
+end