class Osm::Invoice

Constants

SORT_BY

Public Class Methods

get(api, section, invoice_id, options={}) click to toggle source

Get an invoice @param [Osm::Api] api The api to use to make the request @param [Osm::Section, Fixnum, to_i] section The section (or its ID) to get the events for @param [Fixnum, to_i] invoice_id The id of the invoice to get @!macro options_get @return [Osm::Invoice, nil] the invoice (or nil if it couldn't be found

# File lib/osm/invoice.rb, line 91
def self.get(api, section, invoice_id, options={})
  require_ability_to(api, :read, :events, section, options)
  section_id = section.to_i
  invoice_id = invoice_id.to_i
  cache_key = ['invoice', invoice_id]

  if !options[:no_cache] && cache_exist?(api, cache_key)
    return cache_read(api, cache_key)
  end

  invoice_data = api.perform_query("finances.php?action=getInvoice&sectionid=#{section_id}&invoiceid=#{invoice_id}")
  return self.new_invoice_from_data(invoice_data)
end
get_for_section(api, section, options={}) click to toggle source

Get invoices for a section @param [Osm::Api] api The api to use to make the request @param [Osm::Section, Fixnum, to_i] section The section (or its ID) to get the invoices for @!macro options_get @option options [Boolean] :include_archived (optional) if true then archived invoices will also be returned @return [Array<Osm::Invoice>]

# File lib/osm/invoice.rb, line 52
def self.get_for_section(api, section, options={})
  require_ability_to(api, :read, :finance, section, options)
  section_id = section.to_i
  cache_key = ['invoice_ids', section_id]
  invoices = nil

  if !options[:no_cache] && cache_exist?(api, cache_key)
    ids = cache_read(api, cache_key)
    invoices = get_from_ids(api, ids, 'invoice', section, options, :get_for_section)
  end

  if invoices.nil?
    data = api.perform_query("finances.php?action=getInvoices&sectionid=#{section_id}&showArchived=true")
    invoices = Array.new
    ids = Array.new
    unless data['items'].nil?
      data['items'].map { |i| i['invoiceid'].to_i }.each do |invoice_id|
        invoice_data = api.perform_query("finances.php?action=getInvoice&sectionid=#{section_id}&invoiceid=#{invoice_id}")
        invoice = self.new_invoice_from_data(invoice_data)
        invoices.push invoice
        ids.push invoice.id
        cache_write(api, ['invoice', invoice.id], invoice)
      end
    end
    cache_write(api, cache_key, ids)
  end

  return invoices if options[:include_archived]
  return invoices.reject do |invoice|
    invoice.archived?
  end
end

Private Class Methods

new_invoice_from_data(invoice_data) click to toggle source
# File lib/osm/invoice.rb, line 246
def self.new_invoice_from_data(invoice_data)
  invoice_data = invoice_data['invoice']
  return nil unless invoice_data.is_a?(Hash)
  Osm::Invoice.new(
    :id => Osm::to_i_or_nil(invoice_data['invoiceid']),
    :section_id => Osm::to_i_or_nil(invoice_data['sectionid']),
    :name => invoice_data['name'],
    :extra_details => invoice_data['extra'],
    :date => Osm::parse_date(invoice_data['entrydate']),
    :archived => invoice_data['archived'].eql?('1'),
    :finalised => invoice_data['finalised'].eql?('1'),
  )
end

Public Instance Methods

archive(api) click to toggle source

Archive the invoice in OSM, updating the archived attribute if successful. If the archived attribute is true then nothing happens and false is returned. @return [Boolean] Whether the invoice was archived in OSM @raise [Osm::Error] If the invoice does not already exist in OSM

# File lib/osm/invoice.rb, line 175
def archive(api)
  Osm::Model.require_ability_to(api, :write, :finance, section_id)
  raise Osm::Error, 'the invoice does not already exist in OSM' if id.nil?
  return false if archived?

  data = api.perform_query("finances.php?action=deleteInvoice&sectionid=#{section_id}", {
    'invoiceid' => id,
    'archived' => 1,
  })
  if (data.is_a?(Hash) && data['ok'].eql?(true))
    self.archived = true
    # The cached invoice for the section will be out of date - remove it
    cache_delete(api, ['invoice', self.id])
    return true
  end
  return false
end
create(api) click to toggle source

Create the invoice in OSM @return [Boolean] Whether the invoice was created in OSM @raise [Osm::ObjectIsInvalid] If the Invoice is invalid @raise [Osm::Error] If the invoice already exists in OSM

# File lib/osm/invoice.rb, line 110
def create(api)
  raise Osm::Error, 'the invoice already exists in OSM' unless id.nil?
  raise Osm::ObjectIsInvalid, 'invoice is invalid' unless valid?
  Osm::Model.require_ability_to(api, :write, :finance, section_id)

  data = api.perform_query("finances.php?action=addInvoice&sectionid=#{section_id}", {
    'name' => name,
    'extra' => extra_details,
    'date' => date.strftime(Osm::OSM_DATE_FORMAT),
  })
  if data.is_a?(Hash) && !data['id'].nil?
    # The cached invoices for the section will be out of date - remove them
    cache_delete(api, ['invoice_ids', section_id])
    self.id = data['id'].to_i
    return true
  end
  return false
end
delete(api) click to toggle source

Delete the invoice from OSM @return [Boolean] Whether the invoice was deleted from OSM

# File lib/osm/invoice.rb, line 155
def delete(api)
  Osm::Model.require_ability_to(api, :write, :finance, section_id)
  return false if finalised?

  data = api.perform_query("finances.php?action=deleteInvoice&sectionid=#{section_id}", {
    'invoiceid' => id,
  })
  if (data.is_a?(Hash) && data['ok'].eql?(true))
    # The cached invoices for the section will be out of date - remove them
    cache_delete(api, ['invoice_ids', section_id])
    cache_delete(api, ['invoice', self.id])
    return true
  end
  return false
end
finalise(api) click to toggle source

Finalise the invoice in OSM, updating the finalised attribute if successful. If the finalised attribute is true then nothing happens and false is returned. @return [Boolean] Whether the invoice was finalised in OSM @raise [Osm::Error] If the invoice does not already exist in OSM

# File lib/osm/invoice.rb, line 197
def finalise(api)
  Osm::Model.require_ability_to(api, :write, :finance, section_id)
  raise Osm::Error, 'the invoice does not already exist in OSM' if id.nil?
  return false if finalised?

  data = api.perform_query("finances.php?action=finaliseInvoice&sectionid=#{section_id}&invoiceid=#{id}")
  if (data.is_a?(Hash) && data['ok'].eql?(true))
    self.finalised = true
    # The cached invoice for the section will be out of date - remove it
    cache_delete(api, ['invoice', self.id])
    return true
  end
  return false
end
get_items(api, options={}) click to toggle source

Get items for the invoice @param [Osm::Api] api The api to use to make the request @!macro options_get @return [Array<Osm::Invoice::Item>]

# File lib/osm/invoice.rb, line 216
def get_items(api, options={})
  require_ability_to(api, :read, :finance, section_id, options)
  cache_key = ['invoice_items', id]

  if !options[:no_cache] && cache_exist?(api, cache_key)
    return cache_read(api, cache_key)
  end

  items = Array.new
  data = api.perform_query("finances.php?action=getInvoiceRecords&invoiceid=#{id}&sectionid=#{section_id}&dateFormat=generic")
  data['items'].each do |item|
    items.push Osm::Invoice::Item.new(
      :id => Osm::to_i_or_nil(item['id']),
      :invoice => self,
      :record_id => Osm::to_i_or_nil(item['recordid']),
      :date => Osm::parse_date(item['entrydate']),
      :amount => item['amount'],
      :type => item['type'].to_s.downcase.to_sym,
      :payto => item['payto_userid'].to_s.strip,
      :description => item['comments'],
      :budget_name => item['categoryid'],
    )
  end

  cache_write(api, cache_key, items)
  return items
end
update(api) click to toggle source

Update the invoice in OSM @param [Osm::Api] api The api to use to make the request @return [Boolan] whether the invoice was successfully updated or not @raise [Osm::ObjectIsInvalid] If the Invoice is invalid

# File lib/osm/invoice.rb, line 133
def update(api)
  raise Osm::ObjectIsInvalid, 'invoice is invalid' unless valid?
  require_ability_to(api, :write, :finance, section_id)

  data = api.perform_query("finances.php?action=addInvoice&sectionid=#{section_id}", {
    'invoiceid' => id,
    'name' => name,
    'extra' => extra_details,
    'date' => date.strftime(Osm::OSM_DATE_FORMAT),
  })

  if data.is_a?(Hash) && data['ok'].eql?(true)
    reset_changed_attributes
    # The cached invoice will be out of date - remove it
    cache_delete(api, ['invoice', self.id])
    return true
  end
  return false
end