# Change Log
All notable changes to this project will be documented in this file.

## [2.0.19] - 2021-05-xx

### Added
  - Better error message for people searches & **offer** to select among the candidates:
    - `Eco::API::Organization::People::MultipleSearchResults`, triggered from `Eco::API::Organization::People#find`
    - `Eco::API::MicroCases#with_each` will offer the selection of candidates

### Changed
  - **renamed** and repurposed `Eco::API::Organization::PeopleAnalytics` to `PeopleSimilarity`

### Fixed
  - `Eco::Data::FuzzyMatch` adjustments for configuration propagation + some fixes
  - Command option `-entries-from` can still be useful when used to obtain `-get-partial` of people base for `:export` use cases !!

## [2.0.18] - 2021-05-25

### Added
  - **`-one-off`** option to not having to type the `-api-key` every time you launch one-off scripts
    - `-api-key` will store the key to the `./.env_one_off` file (supports update and multi-environment)

### Fixed
  - patched `Exception#patch_full_message` to do not enter into a cyclic error rescue
  - also rescue on `workflow.rescue`

## [2.0.17] - 2021-05-25

Specific changes due to eP **release `1.5.9.70`** (_Policy Group Abilities_)
  - And some improvements as well as new tools

### Added
  - `Eco::API::Organization::PresetsFactory` added integrity validation for `person_abilities` ability
  - `Eco::API::Organization::PresetsFactory`
    - `#validate`: returns an `Array` with all the errors that a `permissions_custom` has
    - `#valid?`: checks if a `permissions_custom` is valid
  - `Eco::API::Organization::PeopleAnalytics`: a **helper** class to identify things in the People Manager and provide mitigation action methods to resolve them.
    - Added dependencies to `fuzzy_match`, `amatch` and `jaro_winkler` **gems**
    - `Eco::Data::FuzzyMatch` with string match helpers and a set of home-made generic libs.
    - `Eco::API::Organization::PeopleAnalytics` to launch analysis on the People Manager
      - `Eco::API::UseCases::DefaultCases::AnalysePeople` invokable via `-analyse-people`
  - **new** -> a way to define a hierarchy of options (at least of 1 Level)
    - `API::CLI::Config::OptionsSet`
    - `API::CLI::Config::UseCases::CaseConfig`
    - Integrated the new feature to the `--help` command and methods.
  - **Usecase** `Eco::API::UseCases::DefaultCases::ResetLandingPageCase` added parameter to specify `-page-id`
  - `Eco::API::Common::BaseLoader` new shortcut methods `#micro` (_MicroCases_), `#session` and `#config`
    - At this stage of the execution workflow it uses `ASSETS.session`
    - **Important note**: when the `#parser` or `#serializer` are called the `ASSETS.session` might already be linked to the specific invoked environment
  - New method helpers in `Ecoporta::API::MicroCases`
    - `preserve_filter_tags`, `preserve_default_tag` and `preserve_policy_groups`

### Changed
  - upgraded dependency on `ecoportal-api` and `ecoportal-api-v2`
  - **removed** `Eco::API::MicroCases#refresh_abilities`
    - `Eco::API::MicroCases#set_account` **removed** `refresh_abilities`
    - `Eco::API::MicroCases#append_usergroups` **removed** `refresh_abilities`
    - **removed** _usecase_ `Eco::API::UseCases::DefaultCases::RefreshAbilitiesCase` (`-refresh-abilities`)
  - `Eco::API::Policies::DefaultPolicies::UserAccess`: **removed** `refresh_abilities`
  - **removed** `Eco::API::Session#new_preset`
  - `Eco::API::Organization::PresetsFactory`
    - **removed** `rspecs`
    - `.new`: **removed** parameters `presets_custom` & `presets_map`
    - **removed** constants `DEFAULT_CUSTOM`, and `DEFAULT_MAP`
    - **removed** private methods `#presets_custom` and `#presets_map`
    - **changed** private method `#compile` receives directly an array of `permissions_custom`
  - `Eco::API::Session::Config` **removed** methods `#presets_custom=` & `presets_map=`
    - `Eco::API::Session::Config::People` **removed** methods `#presets_custom=`, `#presets_map=`,`#presets_custom` & `#presets_map`
  - **removed** `eco/api/organization/presets_reference.json`
  - **moved** case-specific options to only be active when the user case is previously invoked in the command line.

### Fixed
  - **handle** `Ecoportal::API:Errors::TimeOut` in `Eco::API::Session::Batch` by offering to retry.

## [2.0.16] - 2021-05-04

### Added
  - Use case `Eco::API::UseCases::DefaultCases::SupersCyclicIdentify`, invokable via `-identify-cyclic-supers`
  - Use case `Eco::API::UseCases::DefaultCases::AbstractPolicyGroupAbilities`, invokable via `-abstract-policygroup-abilities`
  - Option to run `one-off` scripts, without org configurations:
    1. `-api-key INTERNAL_API_KEY`
    2. `-enviro [live|pre.dev]`
    3. `-org NAME_OF_ORG`

## [2.0.15] - 2021-04-29

### Added
  - Use case `Eco::API::UseCases::DefaultCases::SupersHierarchy`, invokable via `-supers-hierarchy`
### Fixed
  - `eco/cli/config/default/workflow.rb` prevent `rescue` looping

## [2.0.14] - 2021-04-15

### Added
  - `Eco::API::UseCases::DefaultCases::ToCsvCase` added option `-internal-names` to avoid overriding data on export
  - `Eco::API::Common::People::PersonEntry#mapped_entry` exposed method for raw `csv` generation
  - `Eco::API::Organization::PresetsFactory` added integrity validation for `person_*` abilities
  - `Eco::API::Session::Batch::Job` more debug info on erron handlers

### Fixed
  - `Eco::API::Error.get_type` was almost always matching `Eco::API::Error::Unclassified` -> fixed

## [2.0.13] - 2021-03-31

### Added
  - Stats on the `Eco::API::Session::Batch`
  - Allow to inherit and re-use the `Eco::API::UseCases::DefaultCase::HrisCase`

### Fixed
  - Ensure auto-loading for `Eco::API::UseCases`

## [2.0.12] - 2021-03-29

### Changed
  - `Eco::CLI#run` it does include any defined states on the workflow


## [2.0.11] - 2021-03-29

### Fixed
  - `Eco::API::Session::Batch:Errors#errors` changed `Array#filter` call to `Array#select` call

## [2.0.10] - 2021-03-26

### Added
  - `Eco::API::Common::People::PersonParser`
    - `#defined_attrs`: list of all attribute defined parsers (regardless they belong to the model)
  - `Eco::API::Organization::TagTree` methods
    - `#total_depth` to know the total depth of a tree
    - `#flat?` to know if the tagtree has only 1 level

### Changed
  - `Eco::API::Common::People::PersonParser`
    - Renamed `#all_attrs` to `#all_model_attrs`
    - Ranamed `#defined_attrs` to `#defined_model_attrs`
    - Ranamed `#undefined_attrs` to `#undefined_model_attrs`

## [2.0.9] - 2021-03-19

### Changed
  - `Eco::API::Session::Batch:Errors#person_ref` moved to the public method

## [2.0.8] - 2021-03-09

### Fixed
  - `Ecoportal::API::V1::Person#identity` adjust behavior

## [2.0.7] - 2021-03-09

### Fixed
  - `Eco::API::Session::Batch::JobsGroups` and `Eco::API::Session::Batch::Jobs`: when new `Batch::Job`s are creating during launch, they remained unlaunched
    - this fix makes `#launch` method to iterate until there are no pending

## [2.0.6] - 2021-03-08

### Changed
  - `Eco::API::Session::Batch:Errors` moved some methods to be private
### Fixed
  - `Eco::API::Error` should inherit from `StandardError`, rather than from `Exception`

## [2.0.5] - 2021-02-24

### Fixed
  - `Eco::API::Common::People::PersonParser#symbol_keys` to use `Array#select`
    - as `Array#filter` was introduced in ruby `2.5.5`

## [2.0.4] - 2021-02-23

### Changed
  - `Eco::API::Common::People::PersonParser#defined_attrs` to include virtual attributes

## [2.0.3] - 2021-02-23

### Added
  - `Eco::API::UseCases::OozeSamples::OozeUpdateCase`: added integration to update page instances (non-templates)

### Fixed
  - `Eco::API::Policies::DefaultPolicies::UserAccess` complete default policy code.

## [2.0.2] - 2021-02-22

### Changed
  - upgraded dependencies with `ecoportal-api`

## [2.0.1] - 2021-02-22

### Changed
  - upgraded dependencies with `ecoportal-api-oozes` to `ecoportal-api-v2`

## [1.5.15] - 2021-02-17

### Added
  - `Eco::API::Common::ClassHelpers` added support for class methods inheritance
    - this is key to be able to define usecase models to inherit from
  - `Eco::API::UseCases::OozeSamples::OozeUpdateCase`: added this sample to inherit from (simplifying use cases code)
  - `Eco::API::Common::ClassHelpers` added inheritable attribute values
  - added benchmarking to people loaders:
    - `Eco::API::MicroCases#people_load`
    - `Eco::API::MicroCases#people_cache`
    - `Eco::API::MicroCases#people_search`
    - `Eco::API::MicroCases#refresh`

### Fixed
  - `Eco::API::Policies::DefaultPolicies::UserAccess` typos in default api policy

## [1.5.14] - 2021-02-05

### Added
  - `Eco::API::Policies::DefaultPolicies` policies that are run always (after the custom policies)
    - `Eco::API::Policies::DefaultPolicies::UserAccess`:
      - remove account if there's no `email`
      - provision min user level to those with account (if no usergroup and no abilities)
  - `Eco::API::Session#policies` which merges the default policies to be added/run after the custom policies
  - `Eco::API::Common::Session::Logger`: add caching of logs
    - `Eco::API::Common::Session::Logger::Cache` new class to manage cached logs
    - `Eco::API::Common::Session::Logger::Log` new class to have a trace on logs
  - `Eco::API::Session::Batch::Job#summary` added subjobs (error handlers) summary

### Changed
  - `Eco::API::Session::Batch::Job#launch` it will also run the default api policies before feedback and query launch
  - `Eco::API::Common::People::PersonEntry` add error log when wrong email error is detected
    - previously it would have crashed

## [1.5.13] - 2021-02-01

### Changed
  - upgraded dependency with `ecoportal-api-oozes`

### Fixed
  - `Eco::API::Session::Config::Api` was not including the correct `host`
    - this could have launched an `api` request to `live.ecoportal.com` when targeting `pre.dev`

## [1.5.12] - 2021-02-01

### Added
  - `Eco::API::Common::People::DefaultParsers::CSVParser` when cell content is `Null`, capture `nil` value.

### Changed
  - upgraded `ecoportal-api` dependency

## [1.5.11] - 2021-01-25

### Added
  - `Eco::API::Organization::TagTree#subtag?` to check if the tag is in any subtree.

### Fixed
  - `Eco::API::MicroCases#set_supervisor` shouldn't set it if the entry does not have it.

## [1.5.10] - 2021-01-19

### Fixed
  - `Eco::API::Session::Batch::Errors#print` show the row number of the input data.

## [1.5.9] - 2021-01-08

### Added
  - `Eco::API::Organization::TagTree#subtags` to get all the tags but those of the highest level.

## [1.5.8] - 2021-01-05

### Fixed
  - `Eco::API::Session::Batch::Jobs#job` shouldn't be calling the post-launch callback function on creation.
  - `Eco::API::Session#new_job` should include a `&block` parameter.
  - `Eco::API::UseCases::DefaultCases::RefreshCase`: fixed typo

## [1.5.7] - 2020-12-17

### Fixed
  - `Eco::API::Sesssion#parse_attribute` was not using phase argument

## [1.5.6] - 2020-12-04

### Fixed
  - `Eco::API::UseCases::DefaultCases::RestoreDBCase` fixed typo and slightly improved
  - fixed some back-end errors when chaining usecases
  - `Eco::API::UseCases::DefaultCases::OrgDataConvertCase` improved

## [1.5.5] - 2020-12-03

### Fixed
  - rubies previous to `2.5` do not have `yield_self`

## [1.5.4] - 2020-12-02

### Added
  - update `ecoportal-api` dependency
### Fixed
  - `Eco::API::MicroCases#people_refresh` typo

## [1.5.3] - 2020-11-30

### Fixed
  - `Eco::API::Session::Batch::RequestStats#blanked_value?` better blank detection
  - `Eco::API::MicroCases#with_each_starter` rectified typo

## [1.5.2] - 2020-11-26

### Added
  - **custom** usecases, policies and error handlers can now be **declared within its own class**
    * helper classes to inherit from: `Eco::API::Custom::UseCase`, `Eco::API::Custom::Policy`, `Eco::API::Custom::ErrorHandler` and `Eco::API::Custom::Parser`
    * please, notice that you should create new classes under the following namespaces
      - `Custom::UseCase`: custom use cases
      - `Custom::Policy`: custom policy
      - `Custom::ErrorHandler`: custom error handler
      - `Custom::Parser`: custom parser
    * this also allows to inherit from existing defaults and models (models to come)
  - implemented first **microcases** (evaluation stage): to be able to centralize common code between use cases
    - see `Eco::API::MicroCases` class
  - **command line** added `--help` to list all `usecases`, `options` and `filters`
    * `--help -options` will print a documented overview of options
    * `--help -filters` will print a documented overview of people filters
    * `--help -input-filters` will print a documented overview of input data filters
    * `--help -usecases` will print a documented overview of the usecases
  - **command line** filters for `filter_tags` on:
    * input data:  `-input-filter-tags-all`, `input-filter-tags-any`, `input-filter-tags-tree`
    * people data: `-filter-tags-all`, `-filter-tags-any`, `-filter-tags-tree`
  - **batch stats** & **batch policy**
    * `Eco::API::Session::Batch::RequestStats`: included additional guide on what has been **blanked**.
      - now on you should see how many have been blanked, i.e.: `blanked_email`, `blanked_filter_tags`, `blanked_policy_group_ids`, `blanked_supervisor_id`
    * Moreover, the new `blanked_*` properties are available for `config.batch_policies` provided that you can limit the `max` and/or `min` expected on each batch **type**
  - **csv** generation (`-people-to-csv` and `-people-to-csv -detailed`):
     * now includes `"Has Account?"` new column
     * removed the useless `send_invites` column
  - **errors** improved error message when setting values to a `person` from an `entry`:
    * it now shows the **row number**
    * it now gives the specific value that failed in case of `Exception`
  - `Eco::API::Common::DefaultPasers::LoginProvidersParser`: made native
  - `Eco::API::UseCases::DefaultUsecases::TransferAccountCase`: added `-transer-account-from` usecase
    * to allow actually transfer an account/user from one person to another in the org
  - `Ecoportal::API::V1::Person#entry`: method to be able to have a reference to the update/creation input data entry.
  - new filter methods for `Eco::API::Common::People::Entries` and `Eco::API::Organization::People`
    * `#filter_tags_any` & `#filter_tags_all`: those that have any or all the target tags
    * `#policy_group_ids_any` & `#policy_groups_all`: those that have any or all the target policy groups

### Changed
  - updated dependency on `ecoportal-api` gem
  - **command line** some changes:
    - renamed `-refresh-presets` to `-refresh-abilities`
    - renamed `-recover-db` to `restore-db`
  - removed `Eco::API::Session::Tasks`: all the helpers have been moved and documented as part of `Eco::API::MicroCases` (some have been renamed)
    - as a consequence, removed method `Eco::API::Session#do`
  - `Eco::API::Common::People::PersonEntry#to_hash` has been removed
    - now you should use the more explicit `Eco::API::Common::People::PersonEntry#external_entry`
  - **internal refactor** of `Eco::API::UseCases::DefaultCases`:
    * made so they inherit from `Eco::API::Common::Loaders::UseCase` and cases are autoloaded during run-time
  - **internal refactor** of input entries processing:
    * `Eco::API::Common::People::PersonEntry` internal refactor
      - need to make the code clearer and make the `parsing` and `serializing` symmetrical
        - the `serializers` were expecting an `Ecoportal::API::V1::Person`, which was at a different to that of when the `parsers` kicked in.
        - now it has been introduced the possibility to launch the serializer in a different stage of the process
      - to keep backwards compatibility, now it is possible to define at which `phase` of the parsing/serializing each parser and each serializer should kick in, which entailed changes in other classes and a new parameter in some methods thereof...
    * `Eco::Language::Models::ParserSerializer` offers `category` parameter so you can have multiple parsers and serializers per each parser/serializer (one per category).
    * `Eco::API::Common::People::PersonParser` uses `category` to define a `phase` when the `parser` or the `serializer` should be active => the expected object in the parser `callback` will be different depending on at which phase it is active and therefore called
      - for `parser` valid **phases** are `:internal` (default) and `:final`
      - for `serializer` valid **phases** are `:person` (default), `:final` and `:internal`
      - the expected output of such **callbacks** is the same as before: either the single `value` to return or a `Hash` with pair key/values of virtually-generated or existing-modified attributes of the source/input data passed to the parser

### Fixed
  - **command line**
    * `-search-soft` was being ignored in orgs with org config `session.config.people.strict_search = true`
    * Log connection information (**enabled**): it was not printing where the connection was being made
    * enabled chaining between usecases: they will be processed in the order they hold in the command line
  - Removed error double backtrace (now it should only show one)
  - `Eco::API::Common::People::EntryFactory#entries` was not using `encoding` parameter properly.
  - `Eco::API::Common::People::DefaultParsers::CSVParser` does at `strip` (trim) of the header names.
  - `Eco::API::Organization::PresetsFactory#merge` was including abilities that were not included in the custom presets
    - fix: it will include only those that are defined, provided that using it will not override account abilities that should not be targeted, such as `tasks`
    - this new behavior will preserve account abilities that should be preserved; not targeted by the custom presets
  - some use cases where giving incorrect row number, fixed so they do:
    - `Eco::API::Common::People::EntryFactory#entries` adds `idx` key to each `entry`
  - `Eco::API::Common::People::PersonEntry`: serialization process has been normalized (previously there were missing fields)
    - this fix makes the `csv` with the complete set of fields that should be exported
  - `Ecoportal::API::Internal::Person#account_added` fixed typo
  - `Ecoportal::API::Session::Batch#get_people` should return `Array<Person>` invariably

## [1.5.1] - 2020-10-08

### Added
  - `presets_values.json`: added the new ability `tasks` (eP release `1.5.3`)
  - `Ecoportal::API::Internal::Person` patch helper methods:
    * `new?`: to know if this person is new in the people manager as a result of the current launch
    * `account_added?`: to know if this person did not have account but they will have it after the current launch
  - `Eco::API::Session#new_job`: to shorten code
  - `Eco::API::Common::DefaultPasers::PolicyGroupsParser`: made native, as it is a very common parser
  - `Eco::API::Common::DefaultPasers::FreemiumParser` to parse/serialise boolean
  - `Eco::API::Common::People::PersonParser`: added `freemium` as core attribute
  - `Eco::API::UserCases::DefaultCases::RecoverDBCase`: recovers also `freemium`
  - scoping **microcases** : to be able to centralize common code between use cases
    - at its early stage (currently not available for usage)
  - dependency on `ecoportal-api-oozes` gem
    - added basic support for **api** `v2`
    - you can use `session.api(:oozes)` to obtain an api `v2`
    - you can manage your keys directly on the apis configuration
      - added `external_key:`, `user_key:` and `apis.default_user_key`

  ```ruby
  ASSETS.config do |config|
    config.apis.default_user_key = 'your-user-key-here'

    config.add_api("org-environment", {
      host: 'pre.dev.ecoportal.com',
      key:  'an-internal-org-api-key',
      version: :internal,
      external_key: 'an-external-org-api-key',
      user_key: 'org-user-key-for-activity-stream',
      mode:    :local
    })
  end
  ```
### Changed
  - internally: load `Eco::API::Common::Session` before `Eco::API::Common::People`
  - `Eco::API::Common::People::EntryFactory`: made child of `Eco::API::Common::Session::BaseSession`
  - refactored all the `api` connection creation for simplicity and to support multi api version
  - delegated `Eco::API::Session::Batch#get` to `Ecoportal::API::V1::People#get_all`

### Fixed
  - correct `.gemspec` dependency version restrictions

## [1.5.0] - 2020-09-11

### Added
  - `Eco::Data::Files#file_empty?` to prevent error when checking encoding
### Changed
  - change abilities to align with ecoPortal release `1.5.2`
### Fixed
  - `Eco::CSV#parse` and `Eco::CSV#read` should use the proper `encoding` when it's `bom`
    * apparently, this can only be achieved by passing an argument such as `rb:bom|utf-8`
    * best reference found: https://stackoverflow.com/a/60794851/4352306

## [1.4.2] - 2020-07-23

### Fixed
  - preserve backtrace on logging

## [1.4.0] - 2020-07-14

### Changed
  - change abilities to align with ecoPortal release `1.5.0`
  - remove some patches on `ecoportal-api`
  - removed patch method `Ecoportal::API::V1::Person#sync`
### Fixed
  - `Eco::CSV#parse` and `Eco::CSV#read` should use the proper `:encoding` when it's `bom`

## [1.3.19] - 2020-07-23

### Fixed
  - preserve backtrace on logging

## [1.3.18] - 2020-07-08

### Fixed
  - the `update` case was missing the code to use the `default_usergroup`


## [1.3.17] - 2020-07-06

### Changed
  - the `hris` case should not only include as `leavers` those that have account, but anyone that leaves
    * as we could have active people with no account
### Fixed
  - `Eco::API::Session::Batch::Errors#errors`: fix error for empty `body` on response

## [1.3.16] - 2020-06-26

### Added
  - `Eco::API::Common::People::Entries`, `#entry` & `#find` should allow for `strict` search (added parameter)
### Changed
  - upgraded `ecoportal-api` gem dependency to minimum version `0.5.7`
    - this includes the removal of some patches
  - some gems update
### Fixed
  - patched preferences (`kiosk` preferences should default to `nil`)

## [1.3.15] - 2020-06-11

### Added
  - default usecase to export to `csv` (`-detailed`) now includes `"Supervisor Name"` column
### Changed

## [1.3.14] - 2020-06-10

### Added
  - `Eco::API::Common::People::SupervisorHelpers` now has its methods as class methods
### Changed
  - upgraded `ecoportal-api` gem dependency to minimum version `0.5.6`


## [1.3.13] - 2020-05-29

### Fixed
  - `Eco::API::Organization::TagTree#tag?` to accept `nil` by returning `false`
  - `Eco::API::Common::People::DefaultParsers::DateParser` will parse to `Date` class
    * it was parsing to `Time` class, while the native gem `ecoportal-api` parses as `Date` ([reference](https://gitlab.com/ecoPortal/ecoportal-api/-/blob/master/lib/ecoportal/api/v1/schema_field.rb))
## [1.3.12] - 2020-05-19

### Changed
  - stop using `email` as `external_id` on `People#person` & `People#find`
    * this should result in more accurate searches when using `:strict` options

## [1.3.11] - 2020-05-12

### Changed
  - remove popping up comments on `Eco::API::Organization::PolicyGroups#`

## [1.3.10] - 2020-05-12

### Added
  - `Eco::API::Organization::PolicyGroups#to_name` added support for `Array` input
  - `config.people.default_usergroup`, when defined, will have effect on usecases: `update` (this case was missing the change)
    * on account creation, if the input file did not specify `policy_group_ids`

### Fixed
  - `upsert`, `hris` and `create` usecases: fixed condition for use of default_usergroup

## [1.3.9] - 2020-05-12

### Fixed

- `usecase` callback was not receiving `usecase` paramater
  * as a consequence `Batch::Job` created were missing the `usecase`

## [1.3.8] - 2020-05-07

### Added

- this change log file
- `config.people.default_usergroup`, when defined, will have effect on usecases: `create`, `upsert` and `hris`
  * on account creation, if the input file did not specify `policy_group_ids`

### Changed

- `policy` callback to receive new parameter with the `Batch::Job` that it is currently processing/checking

**Example of usage**

```ruby
ASSETS.config.policies do |policies|
  policies.define("update-status") do |people, session, options, policy, job|
    if job.type == :create
      people.each do |person|
        person.details["status"] = "Active" if person.details
      end
    end
    if job.name == "leavers"
      person.details["status"] = "Inactive" if person.details
    end
  end
end
```

### Fixed

- `reinvite` `:sync` native usecase (`-reinvite-from`): should skip people with no account.