eco-helpers 2.0.41 → 2.0.42

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3f9f409fadb3cd263964b4254d35ea3b32cd97ff21eaaef4cd96bb0bafb61b83
-  data.tar.gz: 411187eb287a25f73e75d08fd7ccc6984e3ece935786fd161f3998cfb53a0670
+  metadata.gz: c14b952724b755aa88b633094baf947b8c32b3a8699f77e8a4d63cdc94e10765
+  data.tar.gz: 015fd112ec97cb490c1bae82cdbd744256ca8879b98578f4c2442a0730652bf5
 SHA512:
-  metadata.gz: 7ef199c58c422283f767f90319e6768265a2d38b33e4b5be73ad6b3c77923949056e5263e2130b650307d08deb78d4e0e1da078fcfed70936cb294aa8bb1326f
-  data.tar.gz: aee328dc5617c180ca6efc8e7399a205755b4abb6ff0b8546f19462e2d3a2f095bcc7be6d3b43eb2303b99710fd3bcc881c4421560a37d91b4b0a743bc6e3db6
+  metadata.gz: cbdf02bb1b3323069682c6b9dca370b598d846fc185e8db6dba7e337f1939a41f00b17d60bcb599c4f8abf9c0c6a713495e88258eb5a521b061ffa01c63d552d
+  data.tar.gz: b656b2a52dc65a7e2ae582ec68999de0d7551a6a17c5b83a3763ead94d161a8c969dc76add52ec6a93ebbfd68b5b47293c06fe3e33c8cfaacc4ad6273bf5b17f

data/CHANGELOG.md

@@ -1,10 +1,49 @@
 # Change Log
 All notable changes to this project will be documented in this file.
 
-## [2.0.41] - 2021-09-xx
+## [2.0.42] - 2021-10-30
+
+### Added
+  - `eco/api/organization/presets_values.json` added abilities:
+    - `visitor_management`
+    - `broadcast_notifications`
+    - `cross_register_reporting`
+    - Due to dev pipeline, the `ecoportal-api` version `0.8.4` hasn't been released
+      - This part of the current `eco-helpers` version depends on that gem version (to be upgraded later)
+  - Changed the `workflow` in
+    - `before(:post_launch, :usecases)` => post launch cases are not prevented for **partial** updates
+      - rectified message
+    - `run(:post_launch, :usecases)` => missing **people** error will log in `debug` level
+      - it won't break the script anymore (just prevent a post use case to be run)
+  - New use case `Eco::API::UseCases::DefaultCases::EntriesToCsv`: to export input entries as `csv`
+    - invokable via `-entries-to-csv`
+  - More errors:
+    - `Eco::API::Error::ExternalIdTaken`
+    - `Eco::API::Error::InternalServerError`
+  - **Added** option `processed-people-to-csv file.csv` to export a `csv` with the results of processing people
+    - This option allows to preview the final data when launching a `dry-run` (`-simulate`)
+  - **Added** ooze case sample `Eco::API::UseCases::OozeSamples::TargetOozesUpdateCase`
+    - Allows to retrieve the target entries based on a `csv`
+
+### Changed
+  - Moved methods of `#person_ref`, `#get_attr` and `#get_row` as **class methods** of `Eco::API::Session::Batch::Feedback`
+    - `Eco::API::Session::Errors` methods above to use them via `Feedback` class
+  - `Eco::API::Session::Errors::ErrorCache`: **added** new property `response`
+    - `#by_type` added parameter `only_entries` to specify the output type
+    - `#errors`  capture the `response` in the generated `ErrorCache` object
+
+### Fixed
+  - `Eco::API::Session::Config::Workflow#run` to validate **callback** output class
+    - It should be a `Eco::API::UseCases::BaseIO`
+  - Prevent **uncreated people** to be present in queues or people refresh (if the server side worked perfectly, this contingency shouldn't be necessary):
+    - `Eco::API::Session::Batch::Job#processed_queue`
+      - Sanity-check to exclude people that are **new** and do not have `id` when the current `Job` is **not** of type `:create` (meaning that it was supposed to be created but failed and it probably doesn't exist on server-side)
+      - This prevents errors when trying to update/delete a person that most probably does not exist on the server.
+    - `Eco::API::MicroCases#people_refresh`
+      - Remove from people run-time object those that are **new** that are `dirty` (with pending changes)
+
+## [2.0.41] - 2021-10-06
 
-### Added
-### Changed
 ### Fixed
   - `Eco::API::Session::Batch::Job` `backup_update`
     - Saved `requests` filename was overlapping due to only batch job type being used

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

@@ -166,7 +166,7 @@ module Eco
             run = true
             if Eco::API::Common::Session::FileManager.file_exists?(file)
               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")
+                run = (response == "") || response.upcase.start_with?("Y")
               end
             end
 

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

@@ -1,5 +1,4 @@
 require "net/sftp"
-
 module Eco
   module API
     module Common

data/lib/eco/api/error.rb

@@ -19,10 +19,18 @@ module Eco
         @match     = /.*/
       end
 
+      class InternalServerError < Eco::API::Error
+        @str_err  = "Internal Server Error"
+        @match   = /#{@str_err}/
+      end
       class UnknownPersonId < Eco::API::Error
         @str_err = "Unknown person id"
         @match   = /Cannot find person with id (.*)/
       end
+      class ExternalIdTaken < Eco::API::Error
+        @str_err  = "external ID already taken"
+        @match   = /#{@str_err}/
+      end
       class EmailMissing < Eco::API::Error
         @str_err = "missing email for account creation"
         @match   = /#{@str_err}/

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

@@ -2,15 +2,22 @@ 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.
+      # @note
+      #   1. This helper is normally used to run consecutive usecases, where data needs refresh.
+      #   2. It only includes new people if they are not dirty (they do not have pending updates)
+      #     - This contingency wouldn't be necessary if the server worked perfectly.
       # @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)
+        people = people.newFrom people.select do |person|
+          !person.new? || !person.dirty?
+        end
         ini = people.length
         if include_created
           session.job_groups.find_jobs(type: :create).map do |job|
-            people = people.merge(job.people)
+            to_add = job.people.select {|person| !person.dirty?}
+            people = people.merge(to_add)
           end
         end
 

data/lib/eco/api/organization/presets_values.json

@@ -12,5 +12,8 @@
   "person_core_edit": [null, "edit"],
   "person_details": [null, "view", "edit_public", "view_private", "edit_private"],
   "person_account": [null, "view", "create", "edit"],
-  "person_abilities": [null, "view", "edit"]
+  "person_abilities": [null, "view", "edit"],
+  "visitor_management": [null, "view", "edit", "administrate"],
+  "broadcast_notifications": [null, "view", "administrate"],
+  "cross_register_reporting": [null, "view"]
 }

data/lib/eco/api/session/batch/errors.rb

@@ -8,7 +8,7 @@ module Eco
           # @attr_reader status [Eco::API::Session::Batch::Status] `batch status` this `Errors` object is associated to.
           attr_reader :status
 
-          ErrorCache = Struct.new(:type, :err, :entry)
+          ErrorCache = Struct.new(:type, :err, :entry, :response)
 
           # @param status [Eco::API::Session::Batch::Status] `batch status` this `Errors` object is associated to.
           def initialize(status:)
@@ -46,31 +46,52 @@ module Eco
 
           # @!group Pure errors helper methods
 
+          # @return [Integer] the number of `entries` that got error.
+          def count
+            entries.length
+          end
+
           # Was there any _Sever_ (reply) **error** as a result of this batch?
           # @return [Boolean] `true` if any of the queried _entries_ got an unsuccessful `Ecoportal::API::Common::BatchResponse`
           def any?
             queue.any? {|query| !status[query].success?}
           end
 
-          # @return [Integer] the number of `entries` that got error.
-          def count
-            entries.length
+          # Groups `entries` with error `type`
+          # @return [Hash] where each `key` is a `type` **error** and each value is  an `Array` of:
+          #   1. `entries` that got that error, if `only_entries` is `true`
+          #   2. `ErrorCache` objects, if `only_entries` is `false`
+          def by_type(only_entries: true)
+            errors.group_by do |e|
+              e.type
+            end.transform_values do |arr|
+              if only_entries
+                arr.map {|e| e.entry}
+              else
+                arr
+              end
+            end
           end
+          # @!endgroup
 
-          # For all the `entries` with errors generates a `Hash` object
-          # @return [Array<Hash>] where each `Hash` has
-          #   1. `:type` -> the error type
-          #   2. `:err` -> the error `class` of that `:type`
-          #   3. `:entry` -> the entry that generated the error
+          # For all the `entries` with errors generates an `Array` of `ErrorCache` objects
+          # @return [Array<Eco::API::Session::Batch::Errors::ErrorCache>] where each `object` has
+          #   1. `type`  -> the error type `Class`
+          #   2. `err`   -> an instance object of that error `class` type
+          #   3. `entry` -> the entry that generated the error
+          #   4. `response` -> the original response from the server that carries the error
           def errors
             entries.each_with_object([]) do |entry, arr|
-              if body = status[entry].body
-                if errs = body["errors"]
+              response = status[entry]
+              if body = response.body
+                if errs = body["errors"] || body["error"]
+                  errs = [errs].flatten(1).compact
                   errs.each do |msg|
                     arr.push(ErrorCache.new(
                       klass = Eco::API::Error.get_type(msg),
                       klass.new(err_msg: msg, entry: entry, session: session),
-                      entry
+                      entry,
+                      response
                     ))
                   end
                 end
@@ -78,18 +99,6 @@ module Eco
             end
           end
 
-          # Groups `entries` with error `type`
-          # @return [Hash] where each `key` is a `type` **error** and each value is
-          #   an `Array` of `entries` that got that error
-          def by_type
-            errors.group_by do |e|
-              e.type
-            end.transform_values do |arr|
-              arr.map {|e| e.entry}
-            end
-          end
-          # @!endgroup
-
           # @!group Messaging methods
 
           def message
@@ -112,8 +121,7 @@ module Eco
           # @!endgroup
 
           def person_ref(entry)
-            row_str = (row = get_row(entry)) ? "(row: #{row}) " : nil
-            "#{row_str}(id: '#{get_attr(entry, :id)}') '#{get_attr(entry, :name)}' ('#{get_attr(entry, :external_id)}': '#{get_attr(entry, :email)}')"
+            Eco::API::Session::Batch::Feedback.person_ref(entry)
           end
 
           private
@@ -142,20 +150,11 @@ module Eco
           end
 
           def get_attr(entry, attr)
-            if entry.respond_to?(attr.to_sym)
-              entry.public_send(attr.to_sym)
-            elsif entry.is_a?(Hash)
-              entry["#{attr}"]
-            end
+            Eco::API::Session::Batch::Feedback.get_attr(entry, attr)
           end
 
           def get_row(value)
-            case value
-            when Eco::API::Common::People::PersonEntry
-              value.idx
-            when Ecoportal::API::V1::Person
-              get_row(value.entry)
-            end
+            Eco::API::Session::Batch::Feedback.get_row(value)
           end
 
           # Sorts the entries that got server error by error `type` and generates the error messages.

data/lib/eco/api/session/batch/feedback.rb

@@ -5,6 +5,30 @@ module Eco
         # @attr_reader job [Eco::API::Session::Batch::Job] `batch job` the feedback is associated with
         class Feedback
 
+          class << self
+            def person_ref(entry)
+              row_str = (row = get_row(entry)) ? "(row: #{row}) " : nil
+              "#{row_str}(id: '#{get_attr(entry, :id)}') '#{get_attr(entry, :name)}' ('#{get_attr(entry, :external_id)}': '#{get_attr(entry, :email)}')"
+            end
+
+            def get_attr(entry, attr)
+              if entry.respond_to?(attr.to_sym)
+                entry.public_send(attr.to_sym)
+              elsif entry.is_a?(Hash)
+                entry["#{attr}"]
+              end
+            end
+
+            def get_row(value)
+              case value
+              when Eco::API::Common::People::PersonEntry
+                value.idx
+              when Ecoportal::API::V1::Person
+                get_row(value.entry)
+              end
+            end            
+          end
+
           attr_reader :job
 
           # @param job [Eco::API::Session::Batch::Job] `batch job` the feedback is associated with

data/lib/eco/api/session/batch/job.rb

@@ -235,9 +235,23 @@ module Eco
             end
           end
 
+          # Method to generate the base of people that will be present in the queue
+          # @note
+          #   - If the entry is a new person, we are not in a creation job and the person doesn't have `id`
+          #     it means that it failed to be created (it doesn't exist on server-side).
+          #     The entry won't be included.
+          #   - The contingency above wouldn't be necessary if the server worked perfectly.
           def processed_queue
-            @queue.each {|e| @callbacks[e].call(e) if @callbacks.key?(e) }
-            apply_policies(api_included(@queue)).select do |e|
+            pre_filtered = @queue.select do |entry|
+              if unexisting = entry.new? && !entry.id && type != :create
+                ref = Eco::API::Session::Batch::Feedback.person_ref(entry)
+                msg = "Job ('#{name}':#{type}): excluded unexisting entry (failed creation): #{ref}"
+                session.logger.warn(msg)
+              end
+              !unexisting
+            end
+            pre_filtered.each {|e| @callbacks[e].call(e) if @callbacks.key?(e) }
+            apply_policies(api_included(pre_filtered)).select do |e|
               !as_update(e).empty?
             end.select do |e|
               next true unless e.is_a?(Ecoportal::API::V1::Person)

data/lib/eco/api/session/config/workflow.rb

@@ -185,6 +185,7 @@ module Eco
           #   - it will **not** run the `callback` for `on` defined during the configuration time
           #   - it will rather `yield` the target stage after all the `before` _callbacks_ have been run
           #   - aside of this, the rest will be the same as when the _block_ is provided (see previous note)
+          # @raise [ArgumentError] if the object returned by `before` and `after` callbacks is not an `Eco::API::UseCases::BaseIO`.
           # @param key [Symbol, nil] cases:
           #   - if `key` is not provided, it targets the _current stage_
           #   - if `key` is provided, it targets the specific _sub-stage_
@@ -200,7 +201,16 @@ module Eco
               if key
                 io = stage(key).run(io: io, &block)
               elsif pending?
-                @before.each {|c| io = c.call(self, io)}
+                @before.each do |c|
+                  io = c.call(self, io).tap do |i_o|
+                    unless i_o.is_a?(Eco::API::UseCases::BaseIO)
+                      msg  = "Workflow callaback before('#{name}') should return Eco::API::UseCases::BaseIO object."
+                      msg += " Given #{i_o.class}"
+                      msg += " • Callback source location: '#{c.source_location}'"
+                      raise ArgumentError.new(msg)
+                    end
+                  end
+                end
 
                 unless skip?
                   io.session.logger.debug("(Workflow: #{path}) running now")
@@ -218,7 +228,16 @@ module Eco
                   @pending = false
                 end
 
-                @after.each  {|c| io = c.call(self, io)}
+                @after.each do |c|
+                  io = c.call(self, io).tap do |i_o|
+                    unless i_o.is_a?(Eco::API::UseCases::BaseIO)
+                      msg  = "Workflow callaback after('#{name}') should return Eco::API::UseCases::BaseIO object."
+                      msg += " Given #{i_o.class}"
+                      msg += " • Callback source location: '#{c.source_location}'"
+                      raise ArgumentError.new(msg)
+                    end
+                  end
+                end
               end
             rescue SystemExit
               exit

data/lib/eco/api/usecases/default_cases/entries_to_csv_case.rb

@@ -0,0 +1,18 @@
+class Eco::API::UseCases::DefaultCases::EntriesToCsv < Eco::API::Common::Loaders::UseCase
+  name "entries-to-csv"
+  type :import
+
+  attr_reader :session, :options
+
+  def main(entries, session, options, usecase)
+    @options = options
+    @session = session
+    entries.export(filename)
+  end
+
+  private
+
+  def filename
+    options.dig(:export, :file) || "entries.csv"
+  end
+end

data/lib/eco/api/usecases/default_cases.rb

@@ -24,6 +24,7 @@ require_relative 'default_cases/email_as_id_case'
 require_relative 'default_cases/hris_case'
 require_relative 'default_cases/new_id_case'
 require_relative 'default_cases/new_email_case'
+require_relative 'default_cases/entries_to_csv_case'
 require_relative 'default_cases/org_data_convert_case'
 require_relative 'default_cases/refresh_case'
 require_relative 'default_cases/reinvite_trans_case'

data/lib/eco/api/usecases/ooze_samples/target_oozes_update_case.rb

@@ -0,0 +1,64 @@
+# Use case to update a target oozes
+# @note
+#   - `target_ids` => Expects options[:source][:file] where at least the 1st column should be the target entry `ids`
+class Eco::API::UseCases::OozeSamples::TargetOozesUpdateCase < Eco::API::UseCases::OozeSamples::RegisterUpdateCase
+  name "target-oozes-update-case"
+  type :other
+
+  private
+
+  def with_each_entry
+    batched_target_ids do |ids|
+      ids.each do |id|
+        if pending = queue_shift(id)
+          if dirty?(pending)
+            msg  = "Same entry 'id' appears more than once. "
+            msg << "Launching update on '#{object_reference(pending)}' to be able to queue it back"
+            console.warn msg
+            update_ooze(pending)
+          end
+        end
+        if ooz = ooze(id)
+          yield(ooz)
+        end
+      end
+      update_oozes
+    end
+  end
+
+  def batched_target_ids
+    raise "Missing block. It yields in slices of #{self.class.batch_size} ids" unless block_given?
+    target_ids_preview
+    pool = []
+    target_ids.each do |id|
+      pool << id
+      if pool.length >= self.class.batch_size
+        yield(pool)
+        pool = []
+      end
+    end
+    yield(pool) unless pool.empty?
+  end
+
+  def target_ids_preview
+    dups = target_ids.select {|id| target_ids.count(id) > 1}
+    dups_str = dups.count > 0 ? "There are #{dups.count} duplicated ids" : "No duplicates detected"
+    msg = "Total target entries: #{target_ids.count} (#{dups_str})"
+    session.prompt_user("Do you want to proceed (y/N):", explanation: msg, default: "N", timeout: 10) do |res|
+      unless res.upcase.start_with?("Y")
+        puts "..."
+        logger.info "Aborting script..."
+        exit(0)
+      end
+    end
+  end
+
+  def target_ids
+    @target_ids ||= input_csv.columns.first[1..-1]
+  end
+
+  def input_csv
+    @input_csv ||= Eco::CSV.read(options.dig(:source, :file))
+  end
+
+end

data/lib/eco/api/usecases/ooze_samples.rb

@@ -14,3 +14,4 @@ require_relative 'ooze_samples/ooze_run_base_case'
 require_relative 'ooze_samples/ooze_update_case'
 require_relative 'ooze_samples/ooze_from_doc_case'
 require_relative 'ooze_samples/register_update_case'
+require_relative 'ooze_samples/target_oozes_update_case'

data/lib/eco/cli/config/default/options.rb

@@ -96,6 +96,13 @@ ASSETS.cli.config do |cnf|
       })
     end
 
+    desc  = "Used to export to a csv the final people (after processing). "
+    desc += "It is useful analyse the data after a -dry-run (-simulate)."
+    options_set.add("-processed-people-to-csv", desc) do |options, session|
+      file = SCR.get_file("-processed-people-to-csv", required: true, should_exist: false)
+      options.deep_merge!(report: {people: {csv: file}})
+    end
+
     desc  = "Runs in dry-run (no requests sent to server)"
     options_set.add(["-dry-run", "-simulate"], desc) do |options, session|
       options[:dry_run]  = true

data/lib/eco/cli/config/default/usecases.rb

@@ -137,6 +137,13 @@ ASSETS.cli.config do |cnf|
       end
     end
 
+    desc  = "Input file dump into a CSV as is."
+    cases.add("-entries-to-csv", :import, desc, case_name: "entries-to-csv")
+    .add_option("-out") do |options|
+      file  = SCR.get_file("-out")
+      options.deep_merge(export: {file: file})
+    end
+
     desc  = "Usage '-org-data-convert backup.json -restore-db-from'."
     desc += " Transforms an input .json file to the values of the destination environment "
     desc += " (names missmatch won't solve: i.e. usergroups)"
@@ -196,7 +203,7 @@ ASSETS.cli.config do |cnf|
     .add_option("-append-starters", as1) do |options|
       options.deep_merge!(people: {append_created: true})
     end
-    
+
     desc = "Creates people with only details"
     cases.add("-create-details-from", :sync, desc, case_name: "create-details")
     .add_option("-append-starters", as1) do |options|

data/lib/eco/cli/config/default/workflow.rb

@@ -119,9 +119,7 @@ ASSETS.cli.config do |config|
         else
           wf_post.skip!
           msg = "Although there are post_launch cases, they will NOT be RUN"
-          if !partial_update
-            msg+= ", because it is not a partial update (-get-partial)"
-          elsif io.options[:dry_run]
+          if io.options[:dry_run]
             msg+= ", because we are in dry-run (simulate)."
           end
           io.session.logger.info(msg)
@@ -134,7 +132,15 @@ ASSETS.cli.config do |config|
 
       wf_post.on(:usecases) do |wf_postcases, io|
         io.session.post_launch.each do |use|
-          io = use.launch(io: io).base
+          begin
+            io = use.launch(io: io).base
+          rescue Eco::API::UseCases::BaseIO::MissingParameter => e
+            if e.required == :people
+              io.session.logger.debug("Skipping use case '#{use.name}' -- no base people detected for the current run")
+            else
+              raise
+            end
+          end
         end
         io
       end
@@ -146,8 +152,13 @@ ASSETS.cli.config do |config|
     end
 
     wf.on(:report) do |wf_report, io|
-      #config.reports.active(io: io)
-      #io.session.reports
+      if file = io.options.dig(:report, :people, :csv)
+        io.options.deep_merge!(export: {
+          options: {internal_names: true, nice_header: true, split_schemas: true},
+          file: {name: file, format: :csv}
+        })
+        io = io.session.process_case("to-csv", io: io, type: :export)
+      end
       io
     end
 

data/lib/eco/csv/table.rb

@@ -15,6 +15,7 @@ module Eco
         end
       end
 
+      # It allows to rename the header names
       # @return [Eco::CSV::Table]
       def transform_headers
         header = self.headers
@@ -25,6 +26,8 @@ module Eco
         columns_to_table(cols)
       end
 
+      # When there are headers with the same name, it merges those columns
+      # @note it also offers a way to resolve merge conflicts
       # @return [Eco::CSV::Table]
       def merge_same_header_names
         dups = self.duplicated_header_names

data/lib/eco/version.rb

@@ -1,3 +1,3 @@
 module Eco
-  VERSION = "2.0.41"
+  VERSION = "2.0.42"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: eco-helpers
 version: !ruby/object:Gem::Version
-  version: 2.0.41
+  version: 2.0.42
 platform: ruby
 authors:
 - Oscar Segura
@@ -533,6 +533,7 @@ files:
 - lib/eco/api/usecases/default_cases/delete_sync_case.rb
 - lib/eco/api/usecases/default_cases/delete_trans_case.rb
 - lib/eco/api/usecases/default_cases/email_as_id_case.rb
+- lib/eco/api/usecases/default_cases/entries_to_csv_case.rb
 - lib/eco/api/usecases/default_cases/hris_case.rb
 - lib/eco/api/usecases/default_cases/new_email_case.rb
 - lib/eco/api/usecases/default_cases/new_id_case.rb
@@ -564,6 +565,7 @@ files:
 - lib/eco/api/usecases/ooze_samples/ooze_run_base_case.rb
 - lib/eco/api/usecases/ooze_samples/ooze_update_case.rb
 - lib/eco/api/usecases/ooze_samples/register_update_case.rb
+- lib/eco/api/usecases/ooze_samples/target_oozes_update_case.rb
 - lib/eco/api/usecases/use_case.rb
 - lib/eco/api/usecases/use_case_chain.rb
 - lib/eco/api/usecases/use_case_io.rb