Class: Osm::Invoice

Inherits:
Model
  • Object
show all
Defined in:
lib/osm/invoice.rb

Defined Under Namespace

Classes: Item

Constant Summary collapse

SORT_BY = 
[:section_id, :name, :date]

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Model

#<, #<=, #<=>, #>, #>=, #between?, #changed_attributes, configure, #reset_changed_attributes, #to_i

Constructor Details

#initialize ⇒ Object

Initialize a new Budget

Parameters:

  • attributes (Hash) —

    The hash of attributes (see attributes for descriptions, use Symbol of attribute name as the key)




# File 'lib/osm/invoice.rb', line 41

Instance Attribute Details

#archived ⇒ Boolean

Returns Whether the invoice has been archived.

Returns:

  • (Boolean) —

    Whether the invoice has been archived



21
 
# File 'lib/osm/invoice.rb', line 21

attribute :id, :type => Integer

#date ⇒ Date

Returns When the invoice was created.

Returns:

  • (Date) —

    When the invoice was created



21
 
# File 'lib/osm/invoice.rb', line 21

attribute :id, :type => Integer

#extra_details ⇒ String

Returns Any extra details added to the invoice.

Returns:

  • (String) —

    Any extra details added to the invoice



21
 
# File 'lib/osm/invoice.rb', line 21

attribute :id, :type => Integer

#finalised ⇒ Boolean

Returns Whether the invoice has been finalised.

Returns:

  • (Boolean) —

    Whether the invoice has been finalised



21
 
# File 'lib/osm/invoice.rb', line 21

attribute :id, :type => Integer

#id ⇒ Fixnum

Returns The OSM ID for the invoice.

Returns:

  • (Fixnum) —

    The OSM ID for the invoice



21
 
# File 'lib/osm/invoice.rb', line 21

attribute :id, :type => Integer

#name ⇒ String

Returns The name given to the invoice.

Returns:

  • (String) —

    The name given to the invoice



21
 
# File 'lib/osm/invoice.rb', line 21

attribute :id, :type => Integer

#section_id ⇒ Fixnum

Returns The OSM ID for the section the invoice belongs to.

Returns:

  • (Fixnum) —

    The OSM ID for the section the invoice belongs to



21
 
# File 'lib/osm/invoice.rb', line 21

attribute :id, :type => Integer

Class Method Details

.get(api, section, invoice_id, options = {}) ⇒ Osm::Invoice?

Get an invoice

Parameters:

  • api (Osm::Api) —

    The api to use to make the request

  • section (Osm::Section, Fixnum, #to_i) —

    The section (or its ID) to get the events for

  • invoice_id (Fixnum, #to_i) —

    The id of the invoice to get

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :no_cache (Boolean) — default: optional —

    if true then the data will be retreived from OSM not the cache

Returns:

  • (Osm::Invoice, nil) —

    the invoice (or nil if it couldn’t be found



91
92
93
94
95
96
97
98
99
100
101
102
103
 
# 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 = {}) ⇒ Array<Osm::Invoice>

Get invoices for a section

Parameters:

  • api (Osm::Api) —

    The api to use to make the request

  • section (Osm::Section, Fixnum, #to_i) —

    The section (or its ID) to get the invoices for

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :no_cache (Boolean) — default: optional —

    if true then the data will be retreived from OSM not the cache

  • :include_archived (Boolean) — default: optional —

    if true then archived invoices will also be returned

Returns:



52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
 
# 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

Instance Method Details

#archive(api) ⇒ Boolean

Archive the invoice in OSM, updating the archived attribute if successful. If the archived attribute is true then nothing happens and false is returned.

Returns:

  • (Boolean) —

    Whether the invoice was archived in OSM

Raises:

  • (Osm::Error) —

    If the invoice does not already exist in OSM



175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
 
# 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) ⇒ Boolean

Create the invoice in OSM

Returns:

  • (Boolean) —

    Whether the invoice was created in OSM

Raises:



110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
 
# 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) ⇒ Boolean

Delete the invoice from OSM

Returns:

  • (Boolean) —

    Whether the invoice was deleted from OSM



155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
 
# 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) ⇒ Boolean

Finalise the invoice in OSM, updating the finalised attribute if successful. If the finalised attribute is true then nothing happens and false is returned.

Returns:

  • (Boolean) —

    Whether the invoice was finalised in OSM

Raises:

  • (Osm::Error) —

    If the invoice does not already exist in OSM



197
198
199
200
201
202
203
204
205
206
207
208
209
210
 
# 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 = {}) ⇒ Array<Osm::Invoice::Item>

Get items for the invoice

Parameters:

  • api (Osm::Api) —

    The api to use to make the request

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :no_cache (Boolean) — default: optional —

    if true then the data will be retreived from OSM not the cache

Returns:



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
 
# 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) ⇒ Boolan

Update the invoice in OSM

Parameters:

  • api (Osm::Api) —

    The api to use to make the request

Returns:

  • (Boolan) —

    whether the invoice was successfully updated or not

Raises:



133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
 
# 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