usecases.rb in eco-helpers-2.0.17

- old
+ new

@@ -1,47 +1,74 @@
 ASSETS.cli.config do |cnf|
   cnf.usecases do |cases|
 
-    desc = "Draws the Supervisors hiearchy in a file (use option -to file.ext)"
+    desc = "Draws the Supervisors hiearchy in a file"
     cases.add("-supers-hierarchy", :export, desc, case_name: "supers-hierarchy") do |people, session, options|
-      file = (SCR.get_arg("-to") && SCR.get_file("-to", required: true, should_exist: false)) || "supers_hierarchy.txt"
+      options.deep_merge!(output: {file: "supers_hierarchy.txt"}) unless options.dig(:output, :file)
+    end.add_option("-to", "Specify the output file") do |options|
+      file = SCR.get_file("-to", required: true, should_exist: false)
       options.deep_merge!(output: {file: file})
     end
 
-    desc = "Draws the Cyclic Supervisors when identified (use option -to file.ext)"
+    desc = "Draws the Cyclic Supervisors when identified"
     cases.add("-identify-cyclic-supers", :export, desc, case_name: "identify-cyclic-supers") do |people, session, options|
-      file = (SCR.get_arg("-to") && SCR.get_file("-to", required: true, should_exist: false)) || "supers_hierarchy.txt"
+      options.deep_merge!(output: {file: "cyclic_supers.txt"}) unless options.dig(:output, :file)
+    end.add_option("-to", "Specify the output file") do |options|
+      file = SCR.get_file("-to", required: true, should_exist: false)
       options.deep_merge!(output: {file: file})
     end
 
-    desc = "Abstracts the Abilities that each Usergroup should probably have (use option -to file.ext)"
+    desc = "Abstracts the Abilities that each Usergroup should probably have"
     cases.add("-abstract-policygroup-abilities", :export, desc, case_name: "abstract-policygroup-abilities") do |people, session, options|
-      file = (SCR.get_arg("-to") && SCR.get_file("-to", required: true, should_exist: false)) || "suggested_abilities.txt"
+      options.deep_merge!(output: {file: "suggested_usergroup_abilities.txt"}) unless options.dig(:output, :file)
+    end.add_option("-to", "Specify the output file") do |options|
+      file = SCR.get_file("-to", required: true, should_exist: false)
       options.deep_merge!(output: {file: file})
     end
 
+    desc = "Provides a set of tools to analyse a set of people (i.e. detect duplicates)"
+    cases.add("-analyse-people", :export, desc, case_name: "-analyse-people") do |people, session, options|
+      options.deep_merge!(output: {file: "people_analysis.txt"}) unless options.dig(:output, :file)
+    end.add_option("-to", "Specify the output file") do |options|
+      file = SCR.get_file("-to", required: true, should_exist: false)
+      options.deep_merge!(output: {file: file})
+    end
+
     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")
-      options.deep_merge!(export: {options: {internal_names: true}})  if SCR.get_arg("-internal-names")
-      case_name = SCR.get_arg("-detailed")? "to-csv-detailed" : "to-csv"
+
+      case_name = options.dig(:export, :options, :detailed) ? "to-csv-detailed" : "to-csv"
       session.usecases.case(case_name)
+    end.add_option("-nice-header", "Outputs more descriptive standard headers") do |options|
+      options.deep_merge!(export: {options: {nice_header: true}})
+    end.add_option("-internal-names", "It is the most raw export. Useful to see all the data when name mappings override/overlap") do |options|
+      options.deep_merge!(export: {options: {internal_names: true}})
+    end.add_option("-detailed", "Includes much more information to the file (i.e. permissions_merged abilities, preferences)") do |options|
+      options.deep_merge!(export: {options: {detailed: true}})
+    end.add_option("-permissions-custom", "Used with -detailed. Adds the permissions_custom abilities") do |options|
+      options.deep_merge!(export: {options: {permissions_custom: true}})
     end
 
     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|
+    cases.add("-codes-to-tags-from", :other, desc, case_name: "codes-to-tags-from")
+    .add_option("-codes-to-tags-from", "Specify the input 'csv' file") do |options|
       file = SCR.get_file("-codes-to-tags-from", required: true, should_exist: true)
       options.deep_merge!(other: {file: {name: file, format: :csv}})
-
+    end.add_option("-column", "Specify the input column header with the codes") do |options|
       col_codes = SCR.get_arg("-column", with_param: true)
       options.deep_merge!(other: {file: {codes_column: col_codes}})
     end
 
-    desc = "Removes the landing page"
+    desc = "Removes the landing page or sets it to -page-id"
     cases.add("-reset-landing-page", :transform, desc, case_name: "reset-landing-page")
+    .add_option("-page-id", "Target landing page to set to the users") do |options|
+      SCR.get_arg("-page-id", with_param: true).tap do |new_id|
+        options.deep_merge!({page_id: new_id})
+      end
+    end
 
     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"
@@ -52,27 +79,33 @@
     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)
+      unless options[:super]&.key?(:old)
         msg = "You must specify an -old-super to target whose supervisor is changing"
         session.logger.error(msg)
         exit(1)
       end
-
-      options.deep_merge!(super: {old: old_id})
-
-      unless new_id = SCR.get_arg("-new-super", with_param: true)
+      unless options[:super]&.key?(:new)
         msg = "You must specify the -new-super id. To reset to nil the supervisor, please, specify nil."
         session.logger.error(msg)
         exit(1)
       end
-      new_id = new_id == "nil"? nil : new_id
-      options.deep_merge!(super: {new: new_id})
+    end.add_option("-old-super", "The supervisor id to be replaced on the subordinates") do |options|
+      if old_id = SCR.get_arg("-old-super", with_param: true)
+        old_id = old_id == "nil"? nil : old_id
+        options.deep_merge!(super: {old: old_id})
+      end
+    end.add_option("-new-super", "The new supervisor id") do |options|
+      if new_id = SCR.get_arg("-new-super", with_param: true)
+        new_id = new_id == "nil"? nil : new_id
+        options.deep_merge!(super: {new: new_id})
+      end
     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)"
@@ -81,35 +114,37 @@
         file  = SCR.get_file("-org-data-convert", required: true)
         input = Eco::API::Organization::People.new(JSON.parse(File.read(file)))
         session.logger.info("Source DB: loaded #{input.length} entries.")
       end
 
-      if source_enviro = SCR.get_arg("-source-enviro", with_param: true)
-        options.merge!(source_enviro: source_enviro)
-      else
+      unless options[:source_enviro]
         session.logger.error("You need to specify a -source-enviro for the conversion to work out")
         exit(1)
       end
 
-      options.deep_merge!(ignore: {missing: {policy_groups: true}}) if SCR.get_arg("-ignore-missing-policy-groups")
-
+    end.add_option("-source-enviro", "The defined -source-enviro API configuration that the backup file was generated from") do |options|
+      options.merge!(source_enviro: SCR.get_arg("-source-enviro", with_param: true))
+    end.add_option("-ignore-missing-policy-groups", "Prevents the script to crash when backup file has missing usergroups in the org") do |options|
+      options.deep_merge!(ignore: {missing: {policy_groups: true}})
     end
 
     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("-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
-
-      options.deep_merge!(include: {delete: true}) if SCR.get_arg("-include-delete")
-      options.deep_merge!(include: {create: true}) if SCR.get_arg("-include-create")
+    end.add_option("-include-delete", "If it should DELETE people that do not exist in the backup file") do |options|
+      options.deep_merge!(include: {delete: true})
+    end.add_option("-include-create", "If it should CREATE people that do not exist in the people manager") do |options|
+      options.deep_merge!(include: {create: true})
     end
 
     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")
@@ -128,23 +163,22 @@
     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")})
+    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")
+    .add_option("-include-email", "Specifies if the email should also be moved. Otherwise it only moves the account") do |options|
+      options.deep_merge!(include: {email: true})
     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)"