Module: Maestrano::Connector::Rails::Concerns::Entity

Extended by:
ActiveSupport::Concern
Included in:
Entity
Defined in:
app/models/maestrano/connector/rails/concerns/entity.rb

Defined Under Namespace

Modules: ClassMethods

Instance Method Summary collapse

Instance Method Details

#batch_op(method, mapped_external_entity, id, connec_entity_name) ⇒ Object

Helper method to build an op for batch call See maestrano.github.io/connec/#api-|-batch-calls



289
290
291
292
293
294
295
296
297
298
 
# File 'app/models/maestrano/connector/rails/concerns/entity.rb', line 289

def batch_op(method, mapped_external_entity, id, connec_entity_name)
  Maestrano::Connector::Rails::ConnectorLogger.log('info', @organization, "Sending #{method.upcase} #{connec_entity_name}: #{mapped_external_entity} to Connec! (Preparing batch request)")
  {
    method: method,
    url: "/api/v2/#{@organization.uid}/#{connec_entity_name}/#{id}", # id should be nil for POST
    params: {
      connec_entity_name.to_sym => mapped_external_entity
    }
  }
end

#consolidate_and_map_connec_entities(connec_entities, external_entities, references, external_entity_name) ⇒ Object 



447
448
449
 
# File 'app/models/maestrano/connector/rails/concerns/entity.rb', line 447

def consolidate_and_map_connec_entities(connec_entities, external_entities, references, external_entity_name)
  Maestrano::Connector::Rails::Services::DataConsolidator.new(@organization, self, @opts).consolidate_connec_entities(connec_entities, external_entities, references, external_entity_name)
end

#consolidate_and_map_data(connec_entities, external_entities) ⇒ Object 

General methods

Returns a hash containing the mapped and filtered connec and external entities

  • Discards entities that do not need to be pushed because

    * they date from before the date filtering limit (historical data)
* they are lacking at least one reference (connec entities only)
* they are inactive in the external application
* they are flagged to not be shared (to_connec, to_external)
* they have not been updated since their last push

  • Discards entities from one of the two sources in case of conflict

  • Maps not discarded entities and associates them with their idmap, or create one if there is none



437
438
439
440
441
442
443
444
445
 
# File 'app/models/maestrano/connector/rails/concerns/entity.rb', line 437

def consolidate_and_map_data(connec_entities, external_entities)
  Maestrano::Connector::Rails::ConnectorLogger.log('info', @organization, "Consolidating and mapping #{self.class.external_entity_name}/#{self.class.connec_entity_name}")
  return consolidate_and_map_singleton(connec_entities, external_entities) if self.class.singleton?

  mapped_connec_entities = consolidate_and_map_connec_entities(connec_entities, external_entities, self.class.references, self.class.external_entity_name)
  mapped_external_entities = consolidate_and_map_external_entities(external_entities, self.class.connec_entity_name)

  {connec_entities: mapped_connec_entities, external_entities: mapped_external_entities}
end

#consolidate_and_map_external_entities(external_entities, connec_entity_name) ⇒ Object 



451
452
453
 
# File 'app/models/maestrano/connector/rails/concerns/entity.rb', line 451

def consolidate_and_map_external_entities(external_entities, connec_entity_name)
  Maestrano::Connector::Rails::Services::DataConsolidator.new(@organization, self, @opts).consolidate_external_entities(external_entities, connec_entity_name)
end

#consolidate_and_map_singleton(connec_entities, external_entities) ⇒ Object 



455
456
457
 
# File 'app/models/maestrano/connector/rails/concerns/entity.rb', line 455

def consolidate_and_map_singleton(connec_entities, external_entities)
  Maestrano::Connector::Rails::Services::DataConsolidator.new(@organization, self, @opts).consolidate_singleton(connec_entities, external_entities)
end

#create_external_entity(mapped_connec_entity, external_entity_name) ⇒ Object

To be implemented in each connector



404
405
406
407
 
# File 'app/models/maestrano/connector/rails/concerns/entity.rb', line 404

def create_external_entity(mapped_connec_entity, external_entity_name)
  Maestrano::Connector::Rails::ConnectorLogger.log('info', @organization, "Sending create #{external_entity_name}: #{mapped_connec_entity} to #{Maestrano::Connector::Rails::External.external_name}")
  raise 'Not implemented'
end

#get_connec_entities(last_synchronization_date = nil) ⇒ Object 

Connec! methods

Supported options:

  • full_sync

  • $filter (see Connec! documentation)

  • $orderby (see Connec! documentation)

  • __skip_connec for half syncs

  • __limit and __skip for batch calls

Returns an array of connec entities



206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
 
# File 'app/models/maestrano/connector/rails/concerns/entity.rb', line 206

def get_connec_entities(last_synchronization_date = nil)
  return [] if @opts[:__skip_connec] || !self.class.can_read_connec?

  Maestrano::Connector::Rails::ConnectorLogger.log('info', @organization, "Fetching Connec! #{self.class.connec_entity_name}")

  query_params = {}
  query_params[:$orderby] = @opts[:$orderby] if @opts[:$orderby]

  batched_fetch = @opts[:__limit] && @opts[:__skip]
  if batched_fetch
    query_params[:$top] = @opts[:__limit]
    query_params[:$skip] = @opts[:__skip]
  end

  if last_synchronization_date.blank? || @opts[:full_sync]
    query_params[:$filter] = @opts[:$filter] if @opts[:$filter]
  else
    query_params[:$filter] = "updated_at gt '#{last_synchronization_date.iso8601}'" + (@opts[:$filter] ? " and #{@opts[:$filter]}" : '')
  end

  Maestrano::Connector::Rails::ConnectorLogger.log('debug', @organization, "entity=#{self.class.connec_entity_name}, fetching data with #{query_params.to_query}")
  uri = "#{self.class.normalized_connec_entity_name}?#{query_params.to_query}"
  response_hash = fetch_connec(uri)
  entities = response_hash[self.class.normalized_connec_entity_name]
  entities = [entities] if self.class.singleton?

  # Only the first page if batched_fetch
  unless batched_fetch
    # Fetch subsequent pages
    while response_hash['pagination'] && response_hash['pagination']['next']
      # ugly way to convert https://api-connec/api/v2/group_id/organizations?next_page_params to /organizations?next_page_params
      next_page = response_hash['pagination']['next'].gsub(/\A(.*)\/#{self.class.normalized_connec_entity_name}/, self.class.normalized_connec_entity_name)

      response_hash = fetch_connec(next_page)
      entities.concat response_hash[self.class.normalized_connec_entity_name]
    end
  end

  entities.flatten!
  Maestrano::Connector::Rails::ConnectorLogger.log('info', @organization, "Received data: Source=Connec!, Entity=#{self.class.connec_entity_name}, Data=#{entities}")
  entities
end

#get_external_entities(external_entity_name, last_synchronization_date = nil) ⇒ Object

To be implemented in each connector



311
312
313
314
 
# File 'app/models/maestrano/connector/rails/concerns/entity.rb', line 311

def get_external_entities(external_entity_name, last_synchronization_date = nil)
  Maestrano::Connector::Rails::ConnectorLogger.log('info', @organization, "Fetching #{Maestrano::Connector::Rails::External.external_name} #{external_entity_name.pluralize}")
  raise 'Not implemented'
end

#get_external_entities_wrapper(last_synchronization_date = nil, entity_name = self.class.external_entity_name) ⇒ Object 

External methods

Wrapper to process options and limitations



304
305
306
307
308
 
# File 'app/models/maestrano/connector/rails/concerns/entity.rb', line 304

def get_external_entities_wrapper(last_synchronization_date = nil, entity_name = self.class.external_entity_name)
  return [] if @opts[:__skip_external] || !self.class.can_read_external?

  get_external_entities(entity_name, last_synchronization_date)
end

#map_and_complete_hash_with_connec_ids(external_hash, external_entity_name, connec_hash) ⇒ Object

Returns a completed hash containing id_references with both the connec and external ids



416
417
418
419
420
421
422
423
 
# File 'app/models/maestrano/connector/rails/concerns/entity.rb', line 416

def map_and_complete_hash_with_connec_ids(external_hash, external_entity_name, connec_hash)
  return nil if connec_hash.empty?

  mapped_external_hash = map_to_connec(external_hash)
  references = Maestrano::Connector::Rails::ConnecHelper.format_references(self.class.references)

  Maestrano::Connector::Rails::ConnecHelper.merge_id_hashes(connec_hash, mapped_external_hash, references[:id_references])
end

#map_to_connec(entity, first_time_mapped = nil) ⇒ Object

Map an external entity to Connec! model



184
185
186
187
 
# File 'app/models/maestrano/connector/rails/concerns/entity.rb', line 184

def map_to_connec(entity, first_time_mapped = nil)
  mapper = first_time_mapped ? self.class.creation_mapper_class : self.class.mapper_class
  map_to_connec_helper(entity, mapper, self.class.references)
end

#map_to_connec_helper(entity, mapper, references) ⇒ Object 



189
190
191
192
193
194
 
# File 'app/models/maestrano/connector/rails/concerns/entity.rb', line 189

def map_to_connec_helper(entity, mapper, references)
  mapped_entity = mapper.denormalize(entity, instance_values.with_indifferent_access).merge(id: self.class.id_from_external_entity_hash(entity))
  folded_entity = Maestrano::Connector::Rails::ConnecHelper.fold_references(mapped_entity, references, @organization)
  folded_entity[:opts] = (mapped_entity[:opts] || {}).merge(matching_fields: self.class.connec_matching_fields) if self.class.connec_matching_fields
  folded_entity
end

#map_to_external(entity, first_time_mapped = nil) ⇒ Object 

Mapper methods

Map a Connec! entity to the external model



172
173
174
175
 
# File 'app/models/maestrano/connector/rails/concerns/entity.rb', line 172

def map_to_external(entity, first_time_mapped = nil)
  mapper = first_time_mapped ? self.class.creation_mapper_class : self.class.mapper_class
  map_to_external_helper(entity, mapper)
end

#map_to_external_helper(entity, mapper) ⇒ Object 



177
178
179
180
181
 
# File 'app/models/maestrano/connector/rails/concerns/entity.rb', line 177

def map_to_external_helper(entity, mapper)
  # instance_values returns a hash with all the instance variables (http://apidock.com/rails/v4.0.2/Object/instance_values)
  # that includes opts, organization, connec_client, external_client, and all the connector and entity specific variables
  mapper.normalize(entity, instance_values.with_indifferent_access).with_indifferent_access
end

#push_entities_to_connec(mapped_external_entities_with_idmaps) ⇒ Object

Wrapper TODO, useless? Can be replace by def push_entities_to_connec_to(mapped_external_entities_with_idmaps, connec_entity_name = self.class.connec_entity_name) ?



252
253
254
 
# File 'app/models/maestrano/connector/rails/concerns/entity.rb', line 252

def push_entities_to_connec(mapped_external_entities_with_idmaps)
  push_entities_to_connec_to(mapped_external_entities_with_idmaps, self.class.connec_entity_name)
end

#push_entities_to_connec_to(mapped_external_entities_with_idmaps, connec_entity_name) ⇒ Object

Pushes the external entities to Connec!, and updates the idmaps with either

  • connec_id and push timestamp

  • error message



259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
 
# File 'app/models/maestrano/connector/rails/concerns/entity.rb', line 259

def push_entities_to_connec_to(mapped_external_entities_with_idmaps, connec_entity_name)
  unless @organization.push_to_connec_enabled?(self)
    Maestrano::Connector::Rails::ConnectorLogger.log('info', @organization, "#{Maestrano::Connector::Rails::External.external_name}-#{self.class.external_entity_name.pluralize} not sent to Connec! Push disabled or name not found")
    return
  end

  Maestrano::Connector::Rails::ConnectorLogger.log('info', @organization, "Sending #{Maestrano::Connector::Rails::External.external_name} #{self.class.external_entity_name.pluralize} to Connec! #{connec_entity_name.pluralize}")

  # As we're doing only POST, we use the idmaps to filter out updates
  unless self.class.can_update_connec?
    mapped_external_entities_with_idmaps.reject! { |mapped_external_entity_with_idmap| mapped_external_entity_with_idmap[:idmap].connec_id }
  end

  if self.class.currency_check_fields
    mapped_external_entities_with_idmaps.each do |mapped_external_entity_with_idmap|
      id_map = mapped_external_entity_with_idmap[:idmap]
      next unless id_map&.metadata&.dig(:ignore_currency_update)

      self.class.currency_check_fields.each do |field|
        mapped_external_entity_with_idmap[:entity].delete(field)
      end
    end
  end

  proc = ->(mapped_external_entity_with_idmap) { batch_op('post', mapped_external_entity_with_idmap[:entity], nil, self.class.normalize_connec_entity_name(connec_entity_name)) }
  batch_calls(mapped_external_entities_with_idmaps, proc, connec_entity_name)
end

#push_entities_to_external(mapped_connec_entities_with_idmaps) ⇒ Object

Wrapper TODO, useless? Can be replace by def push_entities_to_external_to(mapped_connec_entities_with_idmaps, external_entity_name = self.class.external_entity_name) ?



319
320
321
 
# File 'app/models/maestrano/connector/rails/concerns/entity.rb', line 319

def push_entities_to_external(mapped_connec_entities_with_idmaps)
  push_entities_to_external_to(mapped_connec_entities_with_idmaps, self.class.external_entity_name)
end

#push_entities_to_external_to(mapped_connec_entities_with_idmaps, external_entity_name) ⇒ Object

Pushes connec entities to the external application Sends new external ids to Connec! (either only the id, or the id + the id references)



325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
 
# File 'app/models/maestrano/connector/rails/concerns/entity.rb', line 325

def push_entities_to_external_to(mapped_connec_entities_with_idmaps, external_entity_name)
  unless @organization.push_to_external_enabled?(self)
    Maestrano::Connector::Rails::ConnectorLogger.log('info', @organization, "#{self.class.connec_entity_name.pluralize} not sent to External! Push disabled or name not found")
    return
  end

  Maestrano::Connector::Rails::ConnectorLogger.log('info', @organization, "Sending Connec! #{self.class.connec_entity_name.pluralize} to #{Maestrano::Connector::Rails::External.external_name} #{external_entity_name.pluralize}")

  entities_to_send_to_connec = mapped_connec_entities_with_idmaps.map { |mapped_connec_entity_with_idmap|
    push_entity_to_external(mapped_connec_entity_with_idmap, external_entity_name)
  }.compact

  # Send the external ids to connec if it was a creation
  # or if there are some sub entities ids to send (completed_hash)
  return if entities_to_send_to_connec.empty?

  # Build a batch op from an idmap and a completed hash
  # with either only the id, or the id + id references
  proc = lambda do |entity|
    id = {id: [Maestrano::Connector::Rails::ConnecHelper.id_hash(entity[:idmap].external_id, @organization)]}
    body = entity[:completed_hash]&.merge(id) || id
    batch_op('put', body, entity[:idmap].connec_id, self.class.normalized_connec_entity_name)
  end
  batch_calls(entities_to_send_to_connec, proc, self.class.connec_entity_name, true)
end

#push_entity_to_external(mapped_connec_entity_with_idmap, external_entity_name) ⇒ Object

Creates or updates connec entity to external Returns nil if there is nothing to send back to Connec! Returns an hash if

- it's a creation: need to send id to Connec! (and potentially id references)
- it's an update but it's the first push of a singleton
- it's an update and there's id references to send to Connec!



357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
 
# File 'app/models/maestrano/connector/rails/concerns/entity.rb', line 357

def push_entity_to_external(mapped_connec_entity_with_idmap, external_entity_name)
  idmap = mapped_connec_entity_with_idmap[:idmap]
  mapped_connec_entity = mapped_connec_entity_with_idmap[:entity]
  id_refs_only_connec_entity = mapped_connec_entity_with_idmap[:id_refs_only_connec_entity]

  begin
    # Create and return id to send to connec!
    if idmap.external_id.blank?
      external_hash = create_external_entity(mapped_connec_entity, external_entity_name)
      idmap.update(external_id: self.class.id_from_external_entity_hash(external_hash), last_push_to_external: Time.now, message: nil)

      return {idmap: idmap, completed_hash: map_and_complete_hash_with_connec_ids(external_hash, external_entity_name, id_refs_only_connec_entity)}
    # Update
    else
      return nil unless self.class.can_update_external?

      external_hash = update_external_entity(mapped_connec_entity, idmap.external_id, external_entity_name)

      completed_hash = map_and_complete_hash_with_connec_ids(external_hash, external_entity_name, id_refs_only_connec_entity)

      # Return the idmap to send it to connec! only if it's the first push of a singleton
      # or if there is a completed hash to send
      if (self.class.singleton? && idmap.last_push_to_external.nil?) || completed_hash
        idmap.update(last_push_to_external: Time.now, message: nil)
        return {idmap: idmap, completed_hash: completed_hash}
      end
      idmap.update(last_push_to_external: Time.now, message: nil)
    end
  rescue => e
    # TODO: improve the flexibility by adding the option for the developer to pass a custom/gem-dependent error
    case e
    when Maestrano::Connector::Rails::Exceptions::EntityNotFoundError
      idmap.update!(message: "The #{external_entity_name} record has been deleted in #{Maestrano::Connector::Rails::External.external_name}. Last attempt to sync on #{Time.now}", external_inactive: true)
      Maestrano::Connector::Rails::ConnectorLogger.log('info', @organization, "The #{idmap.external_entity} - #{idmap.external_id} record has been deleted. It is now set to inactive.")
    else
      # Store External error
      Maestrano::Connector::Rails::ConnectorLogger.log('error', @organization, "Error while pushing to #{Maestrano::Connector::Rails::External.external_name}: #{e}")
      Maestrano::Connector::Rails::ConnectorLogger.log('debug', @organization, "Error while pushing backtrace: #{e.backtrace}")
      idmap.update(message: e.message.truncate(255))
    end
  end

  # Nothing to send to Connec!
  nil
end

#update_external_entity(mapped_connec_entity, external_id, external_entity_name) ⇒ Object

To be implemented in each connector



410
411
412
413
 
# File 'app/models/maestrano/connector/rails/concerns/entity.rb', line 410

def update_external_entity(mapped_connec_entity, external_id, external_entity_name)
  Maestrano::Connector::Rails::ConnectorLogger.log('info', @organization, "Sending update #{external_entity_name} (id=#{external_id}): #{mapped_connec_entity} to #{Maestrano::Connector::Rails::External.external_name}")
  raise 'Not implemented'
end