module Frodo::Concerns::API

Public Instance Methods

count(query) click to toggle source

Public: Count the entity set or for the query passed

entity_set or query - A String or a Frodo::Query. If String is passed,

all entities for the set are counted.
# File lib/frodo/concerns/api.rb, line 235
def count(query)
  url_chunk = if query.is_a?(Frodo::Query)
                query.include_count
                query.to_s
              else
                service[query].query.count
              end

  body = api_get(url_chunk).body

  if query.is_a?(Frodo::Query)
    body['@odata.count']
  else
    # Some servers (*cough* Microsoft *cough*) seem to return
    # extraneous characters in the response.
    # I found out that the _\xef\xbb\xbf  contains probably invisible junk characters
    # called the Unicode BOM (short name for: byte order mark).
    body.scan(/\d+/).first.to_i
  end
end
create(*args) click to toggle source

Public: Insert a new record.

entity_set - The set the entity belongs to attrs - Hash of attributes to set on the new record.

Examples

# Add a new lead
client.create('leads', {"firstname" =>'Bob'})
# => '073ca9c8-2a41-e911-a81d-000d3a1d5a0b'

Returns the primary key value of the newly created entity. Returns false if something bad happens.

# File lib/frodo/concerns/api.rb, line 91
def create(*args)
  create!(*args)
rescue *exceptions
  false
end
Also aliased as: insert
create!(entity_set_name, attrs) click to toggle source

Public: Insert a new record.

entity_set_name - The set the entity belongs to attrs - Hash of attributes to set on the new record.

Examples

# Add a new lead
client.create!('leads', {"firstname" =>'Bob'})
# => '073ca9c8-2a41-e911-a81d-000d3a1d5a0b'

Returns the primary key value of the newly created entity. Raises exceptions if an error is returned from Dynamics.

# File lib/frodo/concerns/api.rb, line 111
def create!(entity_set_name, attrs)
  url = api_post(entity_set_name, attrs).headers['odata-entityid']
  id_match = url.match(/\((.+)\)/)
  if id_match.nil?
    raise Frodo::Error.new "entity url not in expected format: #{url.inspect}"
  end

  return id_match[1]
end
Also aliased as: insert!
destroy(*args) click to toggle source

Public: Delete a record.

entity_set - The set the entity belongs to id - The Dynamics primary key ID of the record.

Examples

# Delete the lead with id  "073ca9c8-2a41-e911-a81d-000d3a1d5a0b"
client.destroy('leads',  "073ca9c8-2a41-e911-a81d-000d3a1d5a0b")

Returns true if the entity was successfully deleted. Returns false if an error is returned from Dynamics.

# File lib/frodo/concerns/api.rb, line 174
def destroy(*args)
  destroy!(*args)
rescue *exceptions
  false
end
destroy!(entity_set, id) click to toggle source

Public: Delete a record.

entity_set - The set the entity belongs to id - The Dynamics primary key ID of the record.

Examples

# Delete the lead with id  "073ca9c8-2a41-e911-a81d-000d3a1d5a0b"
client.destroy!('leads',  "073ca9c8-2a41-e911-a81d-000d3a1d5a0b")

Returns true of the entity was successfully deleted. Raises an exception if an error is returned from Dynamics.

# File lib/frodo/concerns/api.rb, line 192
def destroy!(entity_set, id)
  query = service[entity_set].query
  url_chunk = query.find(id).to_s
  api_delete url_chunk
  true
end
find(entity_set, id) click to toggle source

Public: Finds a single record and returns all fields.

entity_set - The set the entity belongs to id - The id of the record. If field is specified, id should be the id

of the external field.

Returns the Entity record.

# File lib/frodo/concerns/api.rb, line 206
def find(entity_set, id)
  query = service[entity_set].query
  url_chunk = query.find(id)

  body = api_get(url_chunk).body
  build_entity(entity_set, body)
end
insert(*args)
Alias for: create
insert!(entity_set_name, attrs)
Alias for: create!
metadata() click to toggle source

Public: Return the metadata XML schema for the service

Returns [String]

# File lib/frodo/concerns/api.rb, line 38
def metadata
  api_get("$metadata").body
end
metadata_on_init() click to toggle source
# File lib/frodo/concerns/api.rb, line 42
def metadata_on_init
  # Creating Metadata using a different client than the one that is stored
  Frodo::Client.new(@options).api_get("$metadata").body if @options[:with_metadata]
end
query(query) click to toggle source

Public: Execute a query and returns the result.

Query can be the url_chunk per the OData V4 spec or a Frodo::Query. The latter being preferred

Examples

# Find the names of all Accounts
client.query("leads?$filter=firstname eq 'yo'")

or

query = client.service['leads'].query
query.where("firstname eq 'yo'")
client.query(query)

Returns a list of Frodo::Entity

# File lib/frodo/concerns/api.rb, line 64
def query(query)
  url_chunk, entity_set = if query.is_a?(Frodo::Query)
                [query.to_s, query.entity_set.name]
              else
                [query]
              end

  body = api_get(url_chunk).body
  # if manual query as a string we detect the set on the response
  entity_set = body['@odata.context'].split('#')[-1] if entity_set.nil?

  build_entity(entity_set, body)
end
select(entity_set, id, fields) click to toggle source

Public: Finds a single record and returns select fields.

entity_set - The set the entity belongs to id - The id of the record. If field is specified, id should be the id

of the external field.

fields - A String array denoting the fields to select. If nil or empty array

is passed, all fields are selected.
# File lib/frodo/concerns/api.rb, line 221
def select(entity_set, id, fields)
  query = service[entity_set].query

  fields.each{|field| query.select(field)}
  url_chunk = query.find(id)

  body = api_get(url_chunk).body
  build_entity(entity_set, body)
end
update(*args) click to toggle source

Public: Update a record.

entity_set - The set the entity belongs to attrs - Hash of attributes to set on the record.

Examples

# Update the lead with id '073ca9c8-2a41-e911-a81d-000d3a1d5a0b'
client.update('leads', "leadid": '073ca9c8-2a41-e911-a81d-000d3a1d5a0b', Name: 'Whizbang Corp')

Returns true if the entity was successfully updated. Returns false if there was an error.

# File lib/frodo/concerns/api.rb, line 134
def update(*args)
  update!(*args)
rescue *exceptions
  false
end
update!(entity_set_name, primary_key, attrs, additional_headers={}) click to toggle source

Public: Update a record.

entity_set - The set the entity belongs to attrs - Hash of attributes to set on the record.

Examples

# Update the leads with id '073ca9c8-2a41-e911-a81d-000d3a1d5a0b'
client.update!('leads', 'leadid' => '073ca9c8-2a41-e911-a81d-000d3a1d5a0b', "firstname" => 'Whizbang Corp')

Returns true if the entity was successfully updated. Raises an exception if an error is returned from Dynamics.

# File lib/frodo/concerns/api.rb, line 152
def update!(entity_set_name, primary_key, attrs, additional_headers={})
  raise ArgumentError, 'ID field missing from provided attributes' unless attrs.has_key?(primary_key)

  url_chunk = "#{entity_set_name}(#{attrs[primary_key]})"
  api_patch url_chunk, attrs do |req|
    req.headers.merge!(additional_headers)
  end
  true
end

Private Instance Methods

api_path(path) click to toggle source

Internal: Returns a path to an api endpoint based on configured client

Examples

api_path('leads')
# => '/leads'
# File lib/frodo/concerns/api.rb, line 264
def api_path(path)
  "#{options[:base_path]}/#{path}" || "/#{path}"
end
build_entity(entity_set, data) click to toggle source
# File lib/frodo/concerns/api.rb, line 268
def build_entity(entity_set, data)
  if service.with_metadata?
    entity_options = service[entity_set].entity_options
    return single_entity?(data) ? parse_entity(data, entity_options) : parse_entities(data, entity_options)
  end
  single_entity?(data) ? data : data['value']
end
exceptions() click to toggle source

Internal: Errors that should be rescued from in non-bang methods

# File lib/frodo/concerns/api.rb, line 299
def exceptions
  [Faraday::Error::ClientError]
end
parse_entities(body, entity_options) click to toggle source
# File lib/frodo/concerns/api.rb, line 284
def parse_entities(body, entity_options)
  body['value'].map  do |entity_data|
    Frodo::Entity.from_json(entity_data, entity_options)
  end
end
parse_entity(entity_json, entity_options) click to toggle source
# File lib/frodo/concerns/api.rb, line 280
def parse_entity(entity_json, entity_options)
  Frodo::Entity.from_json(entity_json, entity_options)
end
single_entity?(body) click to toggle source
# File lib/frodo/concerns/api.rb, line 276
def single_entity?(body)
  body['@odata.context'] =~ /\$entity$/
end
to_url_chunk(entity) click to toggle source
# File lib/frodo/concerns/api.rb, line 290
def to_url_chunk(entity)
  primary_key = entity.get_property(entity.primary_key).url_value
  set = entity.entity_set.name
  entity.is_new? ? set : "#{set}(#{primary_key})"
end