eco-helpers 1.4.0 → 1.5.2

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

@@ -1,12 +1,28 @@
 ASSETS.cli.config do |cnf|
   cnf.options_set do |options_set, options|
-
-    options_set.add("-schema-id") do |options, session|
+    options_set.add("--help", "offers a help") do |options, sesssion|
+      conf = ASSETS.cli.config
+      puts conf.people_filters.help if hpf = SCR.get_arg("-filters")
+      puts conf.input_filters.help  if hif = SCR.get_arg("-input-filters")
+      puts conf.options_set.help    if ho  = SCR.get_arg("-options")
+      puts conf.usecases.help       if huc = SCR.get_arg("-usecases")
+      puts [
+        "Please specify one of the below:",
+        "  -filters       to display available filters on people",
+        "  -input-filters to display available filters on input data",
+        "  -options       to dislpay available options",
+        "  -usecases      to display available usecases"
+      ].join("\n") unless hpf || hif || ho || huc
+      exit
+    end
+
+    desc = "fix the current session to work with this schema"
+    options_set.add("-schema-id", desc) do |options, session|
       sch_name = SCR.get_arg("-schema-id", with_param: true)
       sch_id   = session.schemas.to_id(sch_name)
 
       unless sch_id
-        msg = "You need to specify a schema id or name. '#{sch_id}' does not exist"
+        msg = "You need to specify a correct schema id or name. '#{sch_name}' does not exist"
         session.logger.error(msg)
         exit(1)
       end
@@ -17,84 +33,103 @@ ASSETS.cli.config do |cnf|
       session.schema = sch_id
     end
 
-    options_set.add("-entries-from") do |options, session|
+    desc = "deprecated: used to be used to specify the input file when using -get-partial"
+    options_set.add("-entries-from", desc) do |options, session|
       options.deep_merge!(input: {entries_from: true})
     end
 
-    options_set.add("-get-people") do |options, session|
+    desc = "locally cache all the people manager by retrieving from the server"
+    options_set.add("-get-people", desc) do |options, session|
       options.deep_merge!(people: {
         get: {from: :remote, type: :full}
       })
     end
 
-    options_set.add(["-dry-run", "-simulate"]) do |options, session|
+    options_set.add(["-dry-run", "-simulate"], "runs in dry-run (no requests sent to server)") do |options, session|
       options[:dry_run]  = true
       options[:simulate] = true
       session.config.dry_run!
     end
 
-    options_set.add("-skip-batch-policy") do |options|
+    desc = "ignores threshold limitations on requests for this session (skip batch belt)"
+    options_set.add("-skip-batch-policy", desc) do |options|
       options.deep_merge!(skip: {batch_policy: true})
     end
 
-    options_set.add("-skip-api-policies") do |options|
+    desc = "will not run the api policies defined for the enviro"
+    options_set.add("-skip-api-policies", desc) do |options|
       options.deep_merge!(skip: {api_policies: true})
     end
 
-    options_set.add("-feed-only-stats") do |options|
+    options_set.add("-feed-only-stats", "shows only stats when giving feedback") do |options|
       options.deep_merge!(feedback: {only_stats: true})
     end
 
+    desc = "deprecated: used to be used to avoid reloading people after launch"
     options[:end_get] = true
-    options_set.add("-no-get") do |options|
+    options_set.add("-no-get", desc) do |options|
       options[:end_get] = false
     end
 
-    options_set.add("-search-strict") do |options|
+    desc  = "force search mode to 'strict' when pairing input entries with existing people."
+    desc += " Besides id and external_id it will not try to find by email unless external_id is not specified"
+    options_set.add("-search-strict", desc) do |options|
       options.deep_merge!(search: {strict: true})
     end
-    options_set.add("-search-soft") do |options|
-      options.deep_merge!(search: {strict: false})
+
+    desc  = "search mode that will try to find people using email when id and external_id have failed"
+    desc += " This option could identify existing people by their email addresses"
+    desc += " (it should not be used in orgs where multiple people usually have the same email address)"
+    options_set.add("-search-soft", desc) do |options|
+      options.deep_merge!(search: {soft: true, strict: false})
     end
 
-    options_set.add(["-no-invites", "-exclude-invites"]) do |options|
+    desc = "silence notifications on account creation or invites"
+    options_set.add(["-no-invites", "-exclude-invites"], desc) do |options|
       options.merge!(send_invites: false)
     end
-    options_set.add("-send-invites") do |options|
+    desc = "people with account will be reinvited if they haven't accepted the invitation"
+    options_set.add("-send-invites", desc) do |options|
       options.merge!(send_invites: true)
     end
 
-    options_set.add("-exclude-core") do |options|
+    options_set.add("-exclude-core", "core input data is not used on the update") do |options|
       options.deep_merge!(exclude: {core: true})
     end
-    options_set.add("-exclude-filter-tags") do |options|
+    options_set.add("-exclude-filter-tags", "filter_tags is not set with the input data") do |options|
       options.deep_merge!(exclude: {filter_tags: true})
     end
-    options_set.add("-exclude-external-id") do |options|
+    options_set.add("-exclude-external-id", "external_id is not set with the input data") do |options|
       options.deep_merge!(exclude: {external_id: true})
     end
-    options_set.add("-exclude-supervisor") do |options|
+    options_set.add("-exclude-supervisor", "supervisor_id is not set with the input data") do |options|
       options.deep_merge!(exclude: {supervisor: true})
     end
-    options_set.add("-exclude-email") do |options|
+    options_set.add("-exclude-email", "email is not set with the input data") do |options|
       options.deep_merge!(exclude: {email: true})
     end
-    options_set.add("-exclude-name") do |options|
+    options_set.add("-exclude-name", "name is not set with the input data") do |options|
       options.deep_merge!(exclude: {name: true})
     end
 
-    options_set.add("-exclude-details") do |options|
+    options_set.add("-exclude-details", "details are not set with the input data") do |options|
       options.deep_merge!(exclude: {details: true})
     end
 
-    options_set.add("-exclude-account") do |options|
+    options_set.add("-exclude-account", "account is not set with the input data") do |options|
       options.deep_merge!(exclude: {account: true})
     end
-    options_set.add("-exclude-policy-groups") do |options|
+    options_set.add("-exclude-policy-groups", "policy_group_ids is not set with the input data") do |options|
       options.deep_merge!(exclude: {policy_groups: true})
     end
-    options_set.add("-exclude-abilities") do |options|
+    options_set.add("-default-tag", "default_tag is not set with the input data") do |options|
+      options.deep_merge!(exclude: {default_tag: true})
+    end
+    options_set.add("-exclude-abilities", "permissions_custom is not set with the input data") do |options|
       options.deep_merge!(exclude: {abilities: true})
     end
+    options_set.add("-exclude-login-providers", "login_provider_ids is not set with the input data") do |options|
+      options.deep_merge!(exclude: {login_providers: true})
+    end
   end
 end

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

@@ -5,7 +5,7 @@ ASSETS.cli.config do |cnf|
       options.deep_merge!(people: {
         get: {from: :remote, type: :full}
       })
-      people = session.do.file_people
+      people = session.micro.people_cache
     elsif SCR.get_arg("-no-people")
       people = Eco::API::Organization::People.new([])
     elsif SCR.get_arg("-people-from-backup")
@@ -23,17 +23,17 @@ ASSETS.cli.config do |cnf|
         get: {from: :remote, type: :partial}
       })
 
-      people = session.do.search(input, options: options)
+      people = session.micro.people_search(input, options: options)
     else
       options.deep_merge!(people: {
         get: {from: :local, type: :full}
       })
-      people = session.do.load_people(modifier: [:newest, :save])
+      people = session.micro.people_load(modifier: [:newest, :save])
       if people.empty?
         options.deep_merge!(people: {
           get: {from: :remote, type: :full}
         })
-        people = session.do.file_people if people.empty?
+        people = session.micro.people_cache if people.empty?
       end
     end
     people

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

@@ -0,0 +1,108 @@
+ASSETS.cli.config do |cnf|
+  cnf.people_filters do |filters|
+
+    filters.add("-only-users", "only those with account") do |people, session, options|
+      options.deep_merge!(people: {filter: {account: true}})
+      people.users
+    end
+
+    filters.add("-no-account", "only those with no account") do |people, session, options|
+      options.deep_merge!(people: {filter: {account: false}})
+      people.account_present(false)
+    end
+
+    filters.add("-with-details", "only those with details") do |people, session, options|
+      options.deep_merge!(people: {filter: {details: true}})
+      people.details_present
+    end
+
+    filters.add("-no-id", "only those with no external_id") do |people, session, options|
+      options.deep_merge!(people: {filter: {external_id: nil}})
+      people.external_id_present(false)
+    end
+
+    filters.add("-supervisors", "only those that have subordinates") do |people, session, options|
+      options.deep_merge!(people: {filter: {subordinates: true}})
+      people.newFrom people.to_a.select {|person| person.subordinates > 0}
+    end
+
+    filters.add("-supervisor-id", "only those with certain supervisor") do |people, session, options|
+      id     = SCR.get_arg("-supervisor-id", with_param: true)
+      options.deep_merge!(people: {filter: {supervisor_id: id}})
+      unless sup = session.micro.with_supervisor(id, people, strict: true)
+        status = session.batch.search([{"id" => id}])
+        sup    = status.people.first
+      end
+      unless sup
+        session.logger.error("Supervisor with id '#{id}' does not exist")
+        exit(1)
+      end
+
+      people.supervisor_id(sup.id)
+    end
+
+    filters.add("-no-default-tag", "only those users with no default tag") do |people, session, options|
+      options.deep_merge!(people: {filter: {account: {default_tag: nil}}})
+      people.users.select do |person|
+        !person.account.default_tag
+      end.yield_self do |filtered|
+        people.newFrom filtered
+      end
+    end
+
+    desc = "only those that have ALL the specified tags separated by '|'"
+    filters.add("-filter-tags-all", desc) do |people, session, options|
+      tags = SCR.get_arg("-filter-tags-all", with_param: true).upcase.split("|")
+      options.deep_merge!(input: {filter: {filter_tags: {any: tags}}})
+      people.filter_tags_all(tags).tap do |filtered|
+        msg = "Filtered #{filtered.count} people (out of #{people.count}) with 'all' filter_tags #{tags}"
+        session.logger.info(msg)
+      end
+    end
+
+    desc = "only those that have ANY the specified tags separated by '|'"
+    filters.add("-filter-tags-any", desc) do |people, session, options|
+      tags = SCR.get_arg("-filter-tags-any", with_param: true).upcase.split("|")
+      options.deep_merge!(input: {filter: {filter_tags_any: tags}})
+      people.filter_tags_any(tags).tap do |filtered|
+        msg = "Filtered #{filtered.count} people (out of #{people.count}) with 'any' filter_tags #{tags}"
+        session.logger.info(msg)
+      end
+    end
+
+    desc = "only those that have ANY tag in the specified subtrees separated by '|'"
+    filters.add("-filter-tags-tree", desc) do |people, session, options|
+      top_tags = SCR.get_arg("-filter-tags-tree", with_param: true).upcase.split("|")
+      tags     = top_tags.each_with_object([])  do |top, tags|
+        tags.concat(session.tagtree.node(top).tags)
+      end.uniq
+      options.deep_merge!(input: {filter: {filter_tags: {tree: top_tags, any: tags}}})
+      people.filter_tags_any(tags).tap do |filtered|
+        msg = "Filtered #{filtered.count} people (out of #{people.count}) with 'any' filter_tags in subtrees #{top_tags}"
+        session.logger.info(msg)
+      end
+    end
+
+    filters.add("-schema-id", "only those with the specified schema id or name") do |people, session, options|
+      sch_name = SCR.get_arg("-schema-id", with_param: true)
+      sch_id   = session.schemas.to_id(sch_name)
+
+      unless sch_id
+        msg = "You need to specify a correct schema id or name. '#{sch_name}' does not exist"
+        session.logger.error(msg)
+        exit(1)
+      end
+
+      options.deep_merge!(people: {filter: {details: {schema_id: sch_id}}})
+      session.logger.info("Filtering people entries with schema #{session.schemas.to_name(sch_id)}")
+
+      people.select do |person|
+        person.details && (person.details.schema_id == sch_id)
+      end.yield_self do |filtered|
+        session.logger.info("Filtered #{filtered.count} people out of #{people.count} total")
+        people.newFrom filtered
+      end
+    end
+
+  end
+end

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

@@ -1,7 +1,8 @@
 ASSETS.cli.config do |cnf|
   cnf.usecases do |cases|
 
-    cases.add("-people-to-csv", :export) do |people, session, options|
+    desc = "It exports to a CSV the (filtered) people"
+    cases.add("-people-to-csv", :export, desc) do |people, session, options|
       file = SCR.get_file("-people-to-csv", required: true, should_exist: false)
       options.deep_merge!(export: {file: {name: file, format: :csv}})
       options.deep_merge!(export: {options: {nice_header: true}}) if SCR.get_arg("-nice-header")
@@ -10,7 +11,8 @@ ASSETS.cli.config do |cnf|
       session.usecases.case(case_name)
     end
 
-    cases.add("-codes-to-tags-from", :other, case_name: "codes-to-tags-from") do |session, options|
+    desc = "Adds a column 'ecoPortalTag' to the input CSV with the tags that the location codes map to"
+    cases.add("-codes-to-tags-from", :other, desc, case_name: "codes-to-tags-from") do |session, options|
       file = SCR.get_file("-codes-to-tags-from", required: true, should_exist: true)
       options.deep_merge!(other: {file: {name: file, format: :csv}})
 
@@ -18,16 +20,24 @@ ASSETS.cli.config do |cnf|
       options.deep_merge!(other: {file: {codes_column: col_codes}})
     end
 
-    cases.add("-reset-landing-page", :transform, case_name: "reset-landing-page")
-    cases.add("-email-as-id", :transform, case_name: "email-as-id")
-    cases.add("-new-id-from", :sync, case_name: "new-id")
-    # won't succeed if some other user with that email in all eP
-    cases.add("-new-email-from", :sync, case_name: "new-email")
-    # forces the change of email no matter what,
-    # unless some other user with that email in the same organization
-    cases.add("-change-email-from", :sync, case_name: "change-email")
-    cases.add("-set-supervisor-from", :sync, case_name: "set-supervisor")
-    cases.add("-switch-supervisor", :transform, case_name: "switch-supervisor") do |people, session, options|
+    desc = "Removes the landing page"
+    cases.add("-reset-landing-page", :transform, desc, case_name: "reset-landing-page")
+
+    desc = "Sets as external_id the email of the person"
+    cases.add("-email-as-id", :transform, desc, case_name: "email-as-id")
+
+    desc = "Sets the external_id to the one given in the input CSV"
+    cases.add("-new-id-from", :sync, desc, case_name: "new-id")
+
+    desc = "Sets the email of people. It won't succeed if email taken by any other user in eP"
+    cases.add("-new-email-from", :sync, desc, case_name: "new-email")
+    desc = "Forces a change of email in the same org. It won't succeed if email taken by an org member user"
+    cases.add("-change-email-from", :sync, desc, case_name: "change-email")
+
+    desc = "Sets the supervisor_id"
+    cases.add("-set-supervisor-from", :sync, desc, case_name: "set-supervisor")
+    desc = "Sets to -new-super the supervisor_id of the -old-super's subordinates"
+    cases.add("-switch-supervisor", :transform, desc, case_name: "switch-supervisor") do |people, session, options|
       unless old_id = SCR.get_arg("-old-super", with_param: true)
         msg = "You must specify an -old-super to target whose supervisor is changing"
         session.logger.error(msg)
@@ -45,15 +55,10 @@ ASSETS.cli.config do |cnf|
       options.deep_merge!(super: {new: new_id})
     end
 
-    cases.add("-create-details-from", :sync, case_name: "create-details")
-    cases.add("-update-details-from", :sync, case_name: "update-details")
-    cases.add("-reinvite", :transform, case_name: "reinvite")
-    cases.add("-reinvite-from", :sync, case_name: "reinvite")
-    cases.add("-set-default-tag", :transform, case_name: "set-default-tag")
-
-    cases.add("-recover-db-from", :sync, case_name: "recover-db") do |input, people, session, options|
+    desc = "Restores the people manager by using a backup.json file"
+    cases.add("-restore-db-from", :sync, desc, case_name: "restore-db") do |input, people, session, options|
       unless input && input.is_a?(Eco::API::Organization::People)
-        file  = SCR.get_file("-recover-db-from", required: true)
+        file  = SCR.get_file("-restore-db-from", required: true)
         input = Eco::API::Organization::People.new(JSON.parse(File.read(file)))
         session.logger.info("Source DB: loaded #{input.length} entries.")
       end
@@ -62,17 +67,49 @@ ASSETS.cli.config do |cnf|
       options.deep_merge!(include: {create: true}) if SCR.get_arg("-include-create")
     end
 
-    cases.add("-create-from", :sync, case_name: "create")
-    cases.add("-append-usergroups-from", :sync, case_name: "append-usergroups")
-    cases.add("-update-from", :sync, case_name: "update")
-    cases.add("-refresh", :transform, case_name: "refresh")
-    cases.add("-refresh-presets", :transform, case_name: "refresh-presets")
-    cases.add("-transfer-account-from", :sync, case_name: "transfer-account")
-    cases.add("-remove-account", :transform, case_name: "remove-account")
-    cases.add("-remove-account-from", :sync, case_name: "remove-account")
-    cases.add("-delete", :transform, case_name: "delete")
-    cases.add("-delete-from", :sync, case_name: "delete")
-    cases.add("-upsert-from", :sync, case_name: "upsert")
-    cases.add("-hris-from", :sync, case_name: "hris")
+    desc = "Re-sends invites to all filtered users that have not accepted the invite as yet"
+    cases.add("-reinvite", :transform, desc, case_name: "reinvite")
+    desc = "Re-sends invites to target users that have not accepted the invite as yet"
+    cases.add("-reinvite-from", :sync, desc, case_name: "reinvite")
+
+    desc = "Deletes everybody that has been filtered from the people manager"
+    cases.add("-delete", :transform, desc, case_name: "delete")
+    desc = "Deletes the people specified in the input data"
+    cases.add("-delete-from", :sync, desc, case_name: "delete")
+    desc = "Removes the account of everybody that has been filtered from the people manager"
+    cases.add("-remove-account", :transform, desc, case_name: "remove-account")
+    desc = "Removes the people specified in the input data"
+    cases.add("-remove-account-from", :sync, desc, case_name: "remove-account")
+
+    desc = "Re-freshes the default_tag of users"
+    cases.add("-set-default-tag", :transform, desc, case_name: "set-default-tag")
+
+    desc = "Creates people with with details and account"
+    cases.add("-create-from", :sync, desc, case_name: "create")
+    desc = "Creates people with only details"
+    cases.add("-create-details-from", :sync, desc, case_name: "create-details")
+
+    desc = "It just adds everybody to an update job without doing any change. If the org has policies, it will refresh"
+    cases.add("-refresh", :transform, desc, case_name: "refresh")
+    desc = "Remaps the abilities of every user based on their usergroups mappings thereof in the org api configuration"
+    cases.add("-refresh-abilities", :transform, desc, case_name: "refresh-abilities")
+
+    desc = "Updates details and core (including supervisor) to target people"
+    cases.add("-update-details-from", :sync, desc, case_name: "update-details")
+
+    desc = "Appends the policy_group_ids column to the people with account specified in the input data"
+    cases.add("-append-usergroups-from", :sync, desc, case_name: "append-usergroups")
+    desc = "Updates the people specified in the input data"
+    cases.add("-update-from", :sync, desc, case_name: "update")
+
+    desc = "Does an actual transfer of user from id|external_id account to 'destination-id' person"
+    cases.add("-transfer-account-from", :sync, desc, case_name: "transfer-account") do |input, people, session, options|
+      options.deep_merge!(include: {email: SCR.get_arg("-include-email")})
+    end
+
+    desc = "Tries to find the input entries and update them. It creates them if not found"
+    cases.add("-upsert-from", :sync, desc, case_name: "upsert")
+    desc = "It does like -upsert-from and additionally removes account and supervisor of those in people that are not in the entries (leavers)"
+    cases.add("-hris-from", :sync, desc, case_name: "hris")
   end
 end

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

@@ -4,7 +4,7 @@ ASSETS.cli.config do |config|
     io = nil
     # default rescue
     wf.rescue do |exception, io|
-      io.session.logger.error(exception.patch_full_message)
+      io.session.logger.debug(exception.patch_full_message)
       wf.run(:close, io: io)
       io
     end
@@ -14,38 +14,42 @@ ASSETS.cli.config do |config|
     end
 
     wf.for(:load) do |wf_load|
-      active_cases = nil
-
-      wf_load.on(:input) do |wf_input, io|
-        active_cases     = config.usecases.active(io: io)
+      wf_load.for(:input) do |wf_input|
+        wf_input.on(:get) do |wf_input_get, io|
+          cases_with_input =  config.usecases.active(io: io).select do |usecase, data|
+            io.class.input_required?(usecase.type)
+          end
+          next io unless (!io.input || io.input.empty?) && !cases_with_input.empty?
 
-        cases_with_input = active_cases.select do |usecase, data|
-          io.class.input_required?(usecase.type)
+          if io.options.dig(:input, :entries_from)
+            io = io.new(input: config.input.get(io: io))
+          else
+            opt_case = cases_with_input.values.first[:option]
+            io = io.new(input: config.input.get(io: io, option: opt_case))
+          end
+          io
         end
 
-        next io unless (!io.input || io.input.empty?) && !cases_with_input.empty?
-
-        if io.options.dig(:input, :entries_from)
-          io = io.new(input: config.input.get(io: io))
-        else
-          opt_case = cases_with_input.values.first[:option]
-          io = io.new(input: config.input.get(io: io, option: opt_case))
+        wf_input.on(:filter) do |wf_input_filter, io|
+          next io unless io.input && !io.input.empty?
+          io = io.new(input:  config.input_filters.process(io: io))
         end
-        io
       end
 
-      wf_load.on(:people) do |wf_people, io|
-        cases_with_people = active_cases.select do |usecase, data|
-          io.class.people_required?(usecase.type)
+      wf_load.for(:people) do |wf_people|
+        wf_people.on(:get) do |wf_people_get, io|
+          cases_with_people = config.usecases.active(io: io).select do |usecase, data|
+            io.class.people_required?(usecase.type)
+          end
+          get_people = io.options.dig(:people, :get, :from) == :remote
+          next io unless !cases_with_people.empty? || get_people
+          io = io.new(people:  config.people(io: io))
         end
-        get_people = io.options.dig(:people, :get, :from) == :remote
-        next io unless !cases_with_people.empty? || get_people
-        io = io.new(people:  config.people(io: io))
-      end
 
-      wf_load.on(:filter) do |wf_filter, io|
-        next io unless io.people && !io.people.empty?
-        io = io.new(people:  config.people_filters.process(io: io))
+        wf_people.on(:filter) do |wf_people_filter, io|
+          next io unless io.people && !io.people.empty?
+          io = io.new(people:  config.people_filters.process(io: io))
+        end
       end
     end
 
@@ -85,7 +89,7 @@ ASSETS.cli.config do |config|
         partial_update = io.options.dig(:people, :get, :type) == :partial
         if !io.options[:dry_run] && partial_update
           # get target people afresh
-          people = io.session.do.people_refresh(people: io.people, include_created: true)
+          people = io.session.micro.people_refresh(people: io.people, include_created: true)
           io     = io.new(people: people)
         else
           wf_post.skip!
@@ -116,10 +120,16 @@ ASSETS.cli.config do |config|
       end
     end
 
+    wf.on(:report) do |wf_report, io|
+      #config.reports.active(io: io)
+      #io.session.reports 
+      io
+    end
+
     wf.on(:end) do |wf_end, io|
       partial_update = io.options.dig(:people, :get, :type) == :partial
       unless !io.options[:end_get] || io.options[:dry_run] || partial_update
-        people = io.session.do.file_people
+        people = io.session.micro.people_cache
         io     = io.new(people: people)
       end
       io