Class: Eco::API::Session

Inherits:
Common::Session::BaseSession show all
Defined in:
lib/eco/api/session.rb,
lib/eco/api/session/batch.rb,
lib/eco/api/session/config.rb,
lib/eco/api/session/batch/job.rb,
lib/eco/api/session/batch/jobs.rb,
lib/eco/api/session/config/api.rb,
lib/eco/api/session/config/apis.rb,
lib/eco/api/session/config/sftp.rb,
lib/eco/api/session/batch/errors.rb,
lib/eco/api/session/batch/status.rb,
lib/eco/api/session/config/files.rb,
lib/eco/api/session/config/logger.rb,
lib/eco/api/session/config/mailer.rb,
lib/eco/api/session/config/people.rb,
lib/eco/api/session/batch/feedback.rb,
lib/eco/api/session/batch/policies.rb,
lib/eco/api/session/config/tagtree.rb,
lib/eco/api/session/config/workflow.rb,
lib/eco/api/session/batch/base_policy.rb,
lib/eco/api/session/batch/jobs_groups.rb,
lib/eco/api/session/config/s3_storage.rb,
lib/eco/api/session/config/base_config.rb,
lib/eco/api/session/config/post_launch.rb,
lib/eco/api/session/batch/request_stats.rb

Overview

Class to manage the current session. Central helper of resources.

Defined Under Namespace

Classes: Batch, Config

Instance Attribute Summary

Attributes inherited from Common::Session::BaseSession

#config, #environment, #session

Attributes included from Language::AuxiliarLogger

#logger

Pure organization helpers collapse

People and Input entries helpers collapse

Session workflow and batch job launces collapse

Additional resources collapse

Instance Method Summary collapse

Methods inherited from Common::Session::BaseSession

#api, #api?, #fatal, #file_manager, #logger, #mailer, #mailer?, #s3uploader, #s3uploader?, #sftp, #sftp?

Methods included from Language::AuxiliarLogger

#log

Constructor Details

#initialize(init = {}) ⇒ Session

Returns a new instance of Session.

Parameters:

Raises:

  • (ArgumentError) 


7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
 
# File 'lib/eco/api/session.rb', line 7

def initialize(init = {})
  env = init

  msg  = "Expected object Eco::API::Session::Config or Eco::API::Common::Session::Environment. "
  msg << " Given: #{init}"

  correct_env = env.is_a?(Session::Config) || env.is_a?(Eco::API::Common::Session::Environment)
  raise ArgumentError, msg unless correct_env

  unless env.is_a?(Eco::API::Common::Session::Environment)
    env = Eco::API::Common::Session::Environment.new(init, session: self)
  end

  super(env)

  @entry_factories  = {}
  @person_factories = {}

  log(:debug) {
    "LINE COMMAND: #{$0} #{ARGV.join(" ")}" # rubocop:disable Style/SpecialGlobalVars
  }
end

Instance Method Details

#batch ⇒ Eco::API::Session::Batch

Returns provides helper to launch batch operations.

Returns:



36
37
38
 
# File 'lib/eco/api/session.rb', line 36

def batch
  @batch ||= Batch.new(enviro)
end

#csv_entries(file, **kargs) ⇒ Eco::API::Common::People::Entries

Generates an entries collection from a csv input file.

Parameters:

  • file (String) —

    file to generate the entries from.

  • data (Array<Hash>) —

    data to be parsed. It cannot be used alongside with file:

  • file (String) —

    absolute or relative path to the input file. It cannot be used alongside with data:.

  • format (Symbol) —

    it must be used when you use the option file: (i.e. :xml, :csv), as it specifies the format of the input file:.

  • options (Hash) —

    further options.

Returns:

See Also:



207
208
209
210
211
212
213
 
# File 'lib/eco/api/session.rb', line 207

def csv_entries(file, **kargs)
  kargs.merge!({
    file:   file,
    format: :csv
  })
  entries(**kargs)
end

#discarded_entries ⇒ Eco::API::Common::People::Entries

Note:

requires session.config.people.discarded_file to be defined.

Generates the collection of entries that should be discarded from an update.

Returns:



218
219
220
221
222
223
224
225
226
 
# File 'lib/eco/api/session.rb', line 218

def discarded_entries
  return @discarded_entries if instance_variable_defined?(:@discarded_entries)

  file = config.people.discarded_file
  file = file_manager.dir.file(file)
  fatal("You have not specified the 'discarded_people_file'") unless file

  @discarded_entries = csv_entries(file)
end

#entries(*args, **kargs) ⇒ Eco::API::Common::People::Entries

Returns collection of entries.

Parameters:

  • data (Array<Hash>) —

    data to be parsed. It cannot be used alongside with file:

  • file (String) —

    absolute or relative path to the input file. It cannot be used alongside with data:.

  • format (Symbol) —

    it must be used when you use the option file: (i.e. :xml, :csv), as it specifies the format of the input file:.

  • options (Hash) —

    further options.

Returns:

See Also:



196
197
198
199
200
 
# File 'lib/eco/api/session.rb', line 196

def entries(*args, **kargs)
  entry_factory.entries(*args, **kargs).tap do |collection|
    log(:info) { "Loaded #{collection.length} input entries." }
  end
end

#entry_factory(schema: nil) ⇒ Eco::API::Common::People::EntryFactory

Helper to obtain a EntryFactory

Parameters:

  • schema (String, Ecoportal::API::V1::PersonSchema) (defaults to: nil) —

    schema to which associate the EntryFactory, where String can be the name or the id of the schema.

Returns:



133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
 
# File 'lib/eco/api/session.rb', line 133

def entry_factory(schema: nil)
  schema = to_schema(schema) || self.schema
  return @entry_factories[schema&.id] if @entry_factories.key?(schema&.id)
  unless @entry_factories.empty?
    @entry_factories[schema&.id] = @entry_factories.values.first.newFactory(schema: schema)
    return @entry_factories[schema&.id]
  end

  @entry_factories[schema&.id] = Eco::API::Common::People::EntryFactory.new(
    enviro,
    schema:        schema,
    person_parser: config.people.parser,
    attr_map:      fields_mapper
  )
end

#enviro_name ⇒ Object 



31
32
33
 
# File 'lib/eco/api/session.rb', line 31

def enviro_name
  config.active_enviro
end

#export(*args) ⇒ Object

Parameters:

  • data (Eco::API::Organization::People) —

    data to be parsed.

  • file (String) —

    absolute or relative path to the ouput file.

  • format (Symbol) —

    it specifies the format of the output file: (i.e. :xml, :csv). There must be a parser/serializer defined for it.

  • encoding (String) —

    optional parameter to geneate file: content by unsing certain encoding.

See Also:



175
176
177
 
# File 'lib/eco/api/session.rb', line 175

def export(*args)
  entry_factory.export(*args)
end

#fields_mapper ⇒ Eco::Data::Mapper

Returns the mappings between the internal and external attribute/property names.

Returns:

  • (Eco::Data::Mapper) —

    the mappings between the internal and external attribute/property names.



119
120
121
122
123
124
125
126
 
# File 'lib/eco/api/session.rb', line 119

def fields_mapper
  return @fields_mapper if instance_variable_defined?(:@fields_mapper)
  mappings = []
  if (map_file = config.people.fields_mapper)
    mappings = map_file ? file_manager.load_json(map_file) : []
  end
  @fields_mapper = Eco::Data::Mapper.new(mappings)
end

#job_group(name, order: :last) ⇒ Eco::API::Session::Batch::Jobs

It retrives the group of Batch::Jobs named name. It creates it if it doesn't exist.

Returns:



284
285
286
287
288
 
# File 'lib/eco/api/session.rb', line 284

def job_group(name, order: :last)
  return job_groups[name] if job_groups.exists?(name)

  job_groups.new(name, order: order)
end

#job_groups ⇒ Eco::API::Session::Batch::JobsGroups

Returns:



278
279
280
 
# File 'lib/eco/api/session.rb', line 278

def job_groups
  @job_groups ||= Batch::JobsGroups.new(enviro)
end

#jobs_launch(simulate: false) ⇒ Object

See Also:



313
314
315
 
# File 'lib/eco/api/session.rb', line 313

def jobs_launch(simulate: false)
  job_groups.launch(simulate: simulate)
end

#live_tree(id: nil, include_archived: false, **kargs, &block) ⇒ Eco::API::Organization::TagTree

Returns:

See Also:



81
82
83
 
# File 'lib/eco/api/session.rb', line 81

def live_tree(id: nil, include_archived: false, **kargs, &block)
  config.live_tree(id: id, include_archived: include_archived, **kargs, &block)
end

#live_trees(include_archived: false, **kargs, &block) ⇒ Object

See Also:



86
87
88
 
# File 'lib/eco/api/session.rb', line 86

def live_trees(include_archived: false, **kargs, &block)
  config.live_trees(include_archived: include_archived, **kargs, &block)
end

#login_providers ⇒ Object

See Also:



48
49
50
 
# File 'lib/eco/api/session.rb', line 48

def 
  config.
end

#mail(**kargs) ⇒ Object

Sends an email

Parameters:

  • to (String) —

    destination email address

  • subject (String) —

    subject of the email

  • body (String) —

    html or plain text message

See Also:



328
329
330
331
332
333
334
335
336
337
 
# File 'lib/eco/api/session.rb', line 328

def mail(**kargs)
  if mailer?
    mailer.mail(**kargs)
  else
    log(:error) {
      "You are trying to use the mailer, but it's not configured"
    }
    nil
  end
end

#micro ⇒ Eco::API::MicroCases

Set of helpers to simplify your code

Returns:

See Also:



263
264
265
 
# File 'lib/eco/api/session.rb', line 263

def micro
  @micro ||= Eco::API::MicroCases.new(enviro)
end

#new_entry(data, dependencies: {}) ⇒ Eco::API::Common::People::PersonEntry

Builds the entry for the given data.

Returns:

See Also:



189
190
191
 
# File 'lib/eco/api/session.rb', line 189

def new_entry(data, dependencies: {})
  entry_factory(schema: data&.details&.schema_id).new(data, dependencies: dependencies)
end

#new_job(group, name, type, usecase, sets = %i[core details account],, accept_update_with_no_id = false, &block) ⇒ Eco::API::Session::Batch::Job

Shortcut to create a job of certain type within a group

Parameters:

Returns:



293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
 
# File 'lib/eco/api/session.rb', line 293

def new_job( # rubocop:disable Metrics/ParameterLists
  group,
  name,
  type,
  usecase,
  sets = %i[core details account],
  accept_update_with_no_id = false, # rubocop:disable Style/OptionalBooleanParameter
  &block
)
  job_group(group).new(
    name,
    usecase:                  usecase,
    type:                     type,
    sets:                     sets,
    accept_update_with_no_id: accept_update_with_no_id,
    &block
  )
end

#new_person(**keyed_args) ⇒ Ecoportal::API::Internal::Person

Parameters:

  • data (Hash, Person) —

    data to be parsed/serialized. Parsed: the external hashed entry. Serialized: a Person object.

Returns:

  • (Ecoportal::API::Internal::Person)

See Also:



182
183
184
 
# File 'lib/eco/api/session.rb', line 182

def new_person(**keyed_args)
  person_factory.new(**keyed_args)
end

#node_classifications(active: true) ⇒ Eco::API::Organization::NodeClassifications

The location node classifications of the organization

Returns:



54
55
56
 
# File 'lib/eco/api/session.rb', line 54

def node_classifications(active: true)
  config.node_classifications(active: active)
end

#parse_attribute(attr, source, phase = :internal, deps: {}) ⇒ Object

Note:

the use of these method requires to know which is the expected format of source

Allows to use the defined parsers

Parameters:

  • attr (String) —

    type (Symbol) or attribute (String) to target a specific parser.

  • source (Any) —

    source value to be parsed.

  • phase (Symbol) (defaults to: :internal) —

    the phase when this parser should be active.

  • phase (Symbol) (defaults to: :internal) —

    the phase when this parser should be active.

Returns:

  • (Object) —

    the parsed attribute.



166
167
168
169
170
171
 
# File 'lib/eco/api/session.rb', line 166

def parse_attribute(attr, source, phase = :internal, deps: {})
  unless (parsers = entry_factory.person_parser)
    raise "There are no parsers defined"
  end
  parsers.parse(attr, source, phase, deps: deps)
end

#person_factory(schema: nil) ⇒ Eco::API::Common::People::PersonFactory

Helper to obtain a PersonFactory

Parameters:

  • schema (String, Ecoportal::API::V1::PersonSchema) (defaults to: nil) —

    schema to which associate the PersonFactory, where String can be the name or the id of the schema.

Returns:



154
155
156
157
 
# File 'lib/eco/api/session.rb', line 154

def person_factory(schema: nil)
  schema = to_schema(schema) || self.schema
  @person_factories[schema&.id] ||= Eco::API::Common::People::PersonFactory.new(schema: schema)
end

#policies ⇒ Eco::API::Policies

Note:
  • the default policies are added at the end (meaning they will run after the custom policies)

Does merge Eco::API::Policies::DefaultPolicies with the custom policies.

Returns:



253
254
255
256
257
258
 
# File 'lib/eco/api/session.rb', line 253

def policies
  @policies ||= config.policies.dup.tap do |policies|
    default_policies = Eco::API::Policies::DefaultPolicies.new
    policies.merge(default_policies)
  end
end

#policy_groups ⇒ Object

See Also:



43
44
45
 
# File 'lib/eco/api/session.rb', line 43

def policy_groups
  config.policy_groups
end

#post_launch ⇒ Object 



267
268
269
 
# File 'lib/eco/api/session.rb', line 267

def post_launch
  @post_launch ||= config.post_launch.select(usecases)
end

#presets_factory ⇒ Object

Helper to state the abilities that a person should have with given their usergroups



114
115
116
 
# File 'lib/eco/api/session.rb', line 114

def presets_factory
  @presets_factory ||= Eco::API::Organization::PresetsFactory.new(enviro: enviro)
end

#process_case(name, io: nil, type: nil, **params) ⇒ Object

See Also:

  • UseCases::Case#launch


272
273
274
275
 
# File 'lib/eco/api/session.rb', line 272

def process_case(name, io: nil, type: nil, **params)
  args = { session: self }.merge(params)
  usecases.case(name, type: type).launch(io: io, **args)
end

#s3upload(content: nil, file: nil, directory: nil, recurse: false, link: false) ⇒ String+

Uploads content into a file, a file or a directory to S3

Parameters:

  • content (String) (defaults to: nil) —

    content to be uploaded (requires file)

  • file (String) (defaults to: nil) —

    name of the file to be uploaded

  • directory (String) (defaults to: nil) —

    name of source directory to be uploaded

  • recurse (Boolean) (defaults to: false) —

    used with directory: deepen in the folder structure? (false: default)

  • link (Boolean) (defaults to: false) —

    return link(s) (true) or path(s) (false: default)

Returns:

  • (String, Array<String>) —

    either paths to S3 objects if link is false, or link otherwise

See Also:



349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
 
# File 'lib/eco/api/session.rb', line 349

def s3upload(content: nil, file: nil, directory: nil, recurse: false, link: false)
  if s3uploader?
    if content == :target
      path = micro.s3upload_targets
    elsif content && file
      path = s3uploader.upload(file, content)
    elsif file
      path = s3uploader.upload_file(file)
    elsif directory
      path = s3uploader.upload_directory(directory, recurse: recurse)
    else
      log(:error) {
        "To use Session.s3upload, you must specify either directory, file or content and file name"
      }
    end
    return path unless link

    s3uploader.link(path)
  else
    log(:error) {
      "You are trying to use S3 uploader, but it's not configured"
    }
    nil
  end
end

#schema ⇒ String, Ecoportal::API::V1::PersonSchema

Returns current active session's schema.

Returns:

  • (String, Ecoportal::API::V1::PersonSchema) —

    current active session's schema



99
100
101
102
 
# File 'lib/eco/api/session.rb', line 99

def schema
  self.schema = config.people.default_schema || schemas.first unless @schema
  @schema
end

#schema=(value) ⇒ Object

Note:

observe that it is essential for the parsers/serialisers to identify target/present attributes.

Sets the current target PersonSchema of this session.

Parameters:

  • value (String, Ecoportal::API::V1::PersonSchema) —

    where String can be the name or the id of the schema.



109
110
111
 
# File 'lib/eco/api/session.rb', line 109

def schema=(value)
  @schema = to_schema(value)
end

#schemas ⇒ Object

See Also:



91
92
93
 
# File 'lib/eco/api/session.rb', line 91

def schemas
  config.schemas
end

#summary ⇒ Object

See Also:



318
319
320
 
# File 'lib/eco/api/session.rb', line 318

def summary
  job_groups.summary
end

#tagtree(live: false, merge: false, include_archived: false, recache: false, **kargs, &block) ⇒ Eco::API::Organization::TagTree

Parameters:

  • live (Boolean) (defaults to: false) —

    states preference of live tree if available over file.

  • merge (Boolean) (defaults to: false) —

    when in live mode, if mulitple trees, merge into one.

Returns:

See Also:



63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
 
# File 'lib/eco/api/session.rb', line 63

def tagtree(
  live:             false,
  merge:            false,
  include_archived: false,
  recache:          false,
  **kargs,
  &block
)
  if live && api?(version: :graphql)
    return live_tree(include_archived: include_archived, **kargs, &block) unless merge
    live_trees(include_archived: include_archived, **kargs, &block).inject(&:merge)
  else
    config.tagtree(recache: recache)
  end
end

#usecases ⇒ Eco::API::UseCases

Note:
  • the order matters, as a default usecase can be redefined by a custom one with same name

Does merge Eco::API::UseCases::DefaultCases with the custom cases.

Returns:



242
243
244
245
246
247
 
# File 'lib/eco/api/session.rb', line 242

def usecases
  @usecases ||= config.usecases.dup.tap do |cases|
    all_cases = Eco::API::UseCases::DefaultCases.new.merge(config.usecases)
    cases.merge(all_cases)
  end
end

#workflow(io:) ⇒ Object

Opens up the workflow configuration



232
233
234
235
236
 
# File 'lib/eco/api/session.rb', line 232

def workflow(io:)
  config.workflow.tap do |wf|
    yield(wf, io) if block_given?
  end
end