eco-helpers 1.5.1 → 1.5.6

data/lib/eco/api/microcases.rb

@@ -1,17 +1,6 @@
 module Eco
   module API
     class MicroCases < Eco::API::Common::Session::BaseSession
-      class << self
-        def define(name, &block)
-          name = name.to_sym
-          @helpers[name] = block
-          define_method(name.to_sym, &block)
-        end
-      end
-
-      def define(*args)
-        self.class.define(*args)
-      end
 
       def micro
         self
@@ -21,11 +10,26 @@ module Eco
   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/set_default_group'
-require_relative 'microcases/set_default_tag'
+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

@@ -1,10 +1,10 @@
 module Eco
   module API
     class MicroCases
-      #self.define(:core_excluded) do |options|
-
-      # @param person [Person] the person we want to update, carrying the changes to be done.
-      # @param options [Hash] the options
+      # @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?

data/lib/eco/api/microcases/{set_default_group.rb → fix_default_group.rb}

@@ -1,20 +1,19 @@
 module Eco
   module API
     class MicroCases
-      #self.define("set_default_group") do |entry, person, session, options|
-
+      # 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 [Person] the person we want to update, carrying the changes to be done.
-      # @param options [Hash] the options
-      def set_default_group(entry, person, options)
+      # @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 || []
+            end_pg_ids = person.account.policy_group_ids
 
-            if person.account_added? && def_usergroup_id && !entry.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_pg_ids = [__def_usergroup_id]
             end
 
             person.account.policy_group_ids = end_pg_ids
@@ -22,7 +21,9 @@ module Eco
         end
       end
 
-      def def_usergroup_id
+      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

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

@@ -1,22 +1,42 @@
 module Eco
   module API
     class MicroCases
-      #self.define(:fix_filter_tags) do |entry, person, options|
-
-      # @param person [Person] the person we want to update, carrying the changes to be done.
-      # @param options [Hash] the options
+      # 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:  true,
-              add_custom:       true
+              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(entries)
+      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

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

@@ -0,0 +1,39 @@
+module Eco
+  module API
+    class MicroCases
+      # Helper to upload target files to `S3`.
+      # @return [Array<String>] the paths in `S3` of the uploaded files.
+      def s3upload_targets
+        [].tap do |paths|
+          session.config.s3storage.target_files.each_with_object(paths) do |file, arr|
+            arr.push(session.s3upload(file: file))
+          end
+          session.config.s3storage.target_directories.each_with_object(paths) do |folder, arr|
+            arr.concat(session.s3upload(directory: folder))
+          end
+          session.config.s3storage.target_file_patterns.each_with_object(paths) do |pattern, arr|
+            filenames = []
+            case pattern
+            when Regexp
+              Dir.entries(".").sort.each do |file|
+                next unless File.file?(file) # Skip directories
+                filenames.push(file) if file =~ pattern
+              end
+            when String
+              Dir.glob(pattern).sort.each do |file|
+                next unless File.file?(file) # Skip directories
+                filenames.push(file)
+              end
+            else
+              # missconfiguration
+            end
+            filenames.each do |file|
+              arr.push(session.s3upload(file: file))
+            end
+          end
+        end
+      end
+
+    end
+  end
+end