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
 
# 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 = {}

  logger.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:



34
35
36
 
# File 'lib/eco/api/session.rb', line 34

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:



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

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:



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

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:



194
195
196
197
198
 
# File 'lib/eco/api/session.rb', line 194

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:



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

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 



29
30
31
 
# File 'lib/eco/api/session.rb', line 29

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:



173
174
175
 
# File 'lib/eco/api/session.rb', line 173

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.



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

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:



282
283
284
285
286
 
# File 'lib/eco/api/session.rb', line 282

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:



276
277
278
 
# File 'lib/eco/api/session.rb', line 276

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

#jobs_launch(simulate: false) ⇒ Object

See Also:



311
312
313
 
# File 'lib/eco/api/session.rb', line 311

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:



79
80
81
 
# File 'lib/eco/api/session.rb', line 79

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:



84
85
86
 
# File 'lib/eco/api/session.rb', line 84

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

#login_providers ⇒ Object

See Also:



46
47
48
 
# File 'lib/eco/api/session.rb', line 46

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:



326
327
328
329
330
331
332
333
 
# File 'lib/eco/api/session.rb', line 326

def mail(**kargs)
  if mailer?
    mailer.mail(**kargs)
  else
    logger.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:



261
262
263
 
# File 'lib/eco/api/session.rb', line 261

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:



187
188
189
 
# File 'lib/eco/api/session.rb', line 187

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:



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

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:



180
181
182
 
# File 'lib/eco/api/session.rb', line 180

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:



52
53
54
 
# File 'lib/eco/api/session.rb', line 52

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.



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

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:



152
153
154
155
 
# File 'lib/eco/api/session.rb', line 152

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:



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

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:



41
42
43
 
# File 'lib/eco/api/session.rb', line 41

def policy_groups
  config.policy_groups
end

#post_launch ⇒ Object 



265
266
267
 
# File 'lib/eco/api/session.rb', line 265

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



112
113
114
 
# File 'lib/eco/api/session.rb', line 112

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


270
271
272
273
 
# File 'lib/eco/api/session.rb', line 270

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:



345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
 
# File 'lib/eco/api/session.rb', line 345

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
      logger.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
    logger.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



97
98
99
100
 
# File 'lib/eco/api/session.rb', line 97

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.



107
108
109
 
# File 'lib/eco/api/session.rb', line 107

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

#schemas ⇒ Object

See Also:



89
90
91
 
# File 'lib/eco/api/session.rb', line 89

def schemas
  config.schemas
end

#summary ⇒ Object

See Also:



316
317
318
 
# File 'lib/eco/api/session.rb', line 316

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:



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

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:



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

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



230
231
232
233
234
 
# File 'lib/eco/api/session.rb', line 230

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