Class: Ecoportal::API::V1::People

Inherits:
Object
  • Object
show all
Extended by:
Common::BaseClass
Includes:
Common::DocHelpers, Enumerable
Defined in:
lib/ecoportal/api/v1/people.rb

Direct Known Subclasses

Internal::People

Defined Under Namespace

Classes: JobStatus

Constant Summary collapse

JOB_TIMEOUT = 
240
DELAY_STATUS_CHECK = 
5

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Common::BaseClass

class_resolver, resolve_class

Methods included from Common::DocHelpers

#get_body, #get_id

Constructor Details

#initialize(client) ⇒ People

Returns an instance object ready to make people api requests.

Parameters:

  • client (Common::Client) —

    a Common::Client object that holds the configuration of the api connection.



19
20
21
 
# File 'lib/ecoportal/api/v1/people.rb', line 19

def initialize(client)
  @client = client
end

Instance Attribute Details

#client ⇒ Common::Client (readonly)

a Common::Client object that holds the configuration of the api connection.

Returns:



5
6
7
 
# File 'lib/ecoportal/api/v1/people.rb', line 5

def client
  @client
end

Instance Method Details

#batch(job_mode: true) {|batch_op| ... } ⇒ Object

Creates a BatchOperation and yields it to the given bock.

Yields:

  • (batch_op) —

    adds multiple api requests for the current batch.

Yield Parameters:

  • batch_op (BatchOperation) 


120
121
122
123
124
125
126
127
128
129
130
 
# File 'lib/ecoportal/api/v1/people.rb', line 120

def batch(job_mode: true, &block)
  return job(&block) if job_mode
  operation = Common::BatchOperation.new("/people", person_class, logger: client.logger)
  yield operation
  # The batch operation is responsible for logging the output
  client.without_response_logging do
    client.post("/people/batch", data: operation.as_json).tap do |response|
      operation.process_response(response)
    end
  end
end

#create(doc) ⇒ Response

Requests to create a person via api.

Parameters:

  • doc (Person, Hash) —

    data that at least contains an id (internal or external) of the target person.

Returns:

  • (Response) —

    an object with the api response.



95
96
97
98
 
# File 'lib/ecoportal/api/v1/people.rb', line 95

def create(doc)
  body = get_body(doc)
  client.post("/people", data: body)
end

#delete(doc) ⇒ Response

Requests to completelly remove from an organization an existing person via api.

Parameters:

  • doc (Person, Hash) —

    data that at least contains an id (internal or external) of the target person.

Returns:

  • (Response) —

    an object with the api response.



112
113
114
115
 
# File 'lib/ecoportal/api/v1/people.rb', line 112

def delete(doc)
  id = get_id(doc)
  client.delete("/people/"+CGI.escape(id))
end

#each(params: {}, silent: false) {|person| ... } ⇒ Object

Note:
  • it ignores the key cursor_id: of params:.
  • each is called by to_a

Iterates all the people of the organization.

Parameters:

  • params (Hash) (defaults to: {})
  • silent (Boolean) (defaults to: false) —

    false to show percentage of progress.

Options Hash (params:):

  • :per_page (String) —

    the number of people you get per request.

  • :q (String) —

    some text to search. Omit this parameter to target all the people.

Yields:

  • (person) —

    does some stuff with the person.

Yield Parameters:



33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
 
# File 'lib/ecoportal/api/v1/people.rb', line 33

def each(params: {}, silent: false, &block)
  return to_enum(:each, params: params, silent: silent) unless block
  cursor_id = nil; results = 0
  puts "\n" unless silent
  loop do
    params.update(cursor_id: cursor_id) if cursor_id
    response = client.get("/people", params: params)
    body     = body_data(response.body)
    raise "Request failed - Status #{response.status}: #{body}" unless response.success?

    unless silent || (total = body["total_results"]) == 0
      results += body["results"].length
      percent  = results * 100 / total
      msg      = "People GET"
      msg     += " (search=#{params[:q]})" if params.key?(:q)
      print "#{msg}: #{percent.round}% (of #{total})\r"
      $stdout.flush
    end

    body["results"].each do |person|
      yield person_class.new(person)
    end
    break unless (cursor_id = body["cursor_id"])
  end
  self
end

#get(doc) ⇒ Person

Note:

if the request has success? the returned object.result gives an object with that Person.

Gets a person via api.

Parameters:

  • doc (String, Hash, Person) —

    data containing an id (internal or external) of the target person.

Returns:

  • (Person) —

    the person with id (internal or external) contained in doc.



75
76
77
78
79
80
81
 
# File 'lib/ecoportal/api/v1/people.rb', line 75

def get(doc)
  id       = get_id(doc)
  response = client.get("/people/"+CGI.escape(id))
  body     = body_data(response.body)
  return person_class.new(body) if response.success?
  raise "Could not get person #{id} - Error #{reponse.status}: #{body}"
end

#get_all(params: {}, silent: false) ⇒ Array<Person>

Note:

it ignores the key :cursor_id in params:.

Gets all the people via api requests.

Parameters:

  • params (Hash) (defaults to: {})
  • silent (Boolean) (defaults to: false) —

    false to show percentage of progress.

Options Hash (params:):

  • :per_page (Integer) —

    the number of people you get per request.

  • :q (String) —

    some text to search.

Returns:

  • (Array<Person>) —

    the array of people got via api.



67
68
69
 
# File 'lib/ecoportal/api/v1/people.rb', line 67

def get_all(params: {}, silent: false)
  each(params: params, silent: silent).to_a
end

#job {|operation| ... } ⇒ Object

Yields:

  • (operation) 


132
133
134
135
136
137
138
139
140
141
142
143
144
 
# File 'lib/ecoportal/api/v1/people.rb', line 132

def job
  operation = Common::BatchOperation.new("/people", person_class, logger: client.logger)
  yield operation
  # The batch operation is responsible for logging the output
  job_id = create_job(operation)
  status = wait_for_job_completion(job_id)

  if status&.complete?
    operation.process_response job_result(job_id, operation)
  else
    raise "Job `#{job_id}` not complete. Probably timeout after #{JOB_TIMEOUT} seconds. Current status: #{status}"
  end
end

#new ⇒ Person

Creates a new Person object.

Returns:

  • (Person) —

    new empty person object of the current version.



148
149
150
 
# File 'lib/ecoportal/api/v1/people.rb', line 148

def new
  person_class.new
end

#update(doc) ⇒ Response

Requests an update of a person via api.

Parameters:

  • doc (Person, Hash) —

    data that at least contains an id (internal or external) of the target person.

Returns:

  • (Response) —

    an object with the api response.



86
87
88
89
90
 
# File 'lib/ecoportal/api/v1/people.rb', line 86

def update(doc)
  body = get_body(doc)
  id   = get_id(doc)
  client.patch("/people/"+CGI.escape(id), data: body)
end

#upsert(doc) ⇒ Response

Requests to update an existing person or if it does not exist, to create it, via api.

Parameters:

  • doc (Person, Hash) —

    data that at least contains an id (internal or external) of the target person.

Returns:

  • (Response) —

    an object with the api response.



103
104
105
106
107
 
# File 'lib/ecoportal/api/v1/people.rb', line 103

def upsert(doc)
  body = get_body(doc)
  id   = get_id(doc)
  client.post("/people/"+CGI.escape(id), data: body)
end