class Osm::Invoice
Constants
- SORT_BY
Public Class Methods
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§ionid=#{section_id}&invoiceid=#{invoice_id}") return self.new_invoice_from_data(invoice_data) end
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§ionid=#{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§ionid=#{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
# 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 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§ionid=#{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 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§ionid=#{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 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§ionid=#{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 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§ionid=#{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 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}§ionid=#{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 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§ionid=#{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