elmas 1.0.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 31ec8dd25ceb6a01b7d07b240c16b8d33616cb33
-  data.tar.gz: 6877c0e58d2ba5c5ff77eba97a599e5ecf220ef7
+  metadata.gz: 4405c4e143b2a041bd2b2bda762788051e196143
+  data.tar.gz: 79f57ea2506232679f28c47c531041415f823765
 SHA512:
-  metadata.gz: 2c9aecd1f8e78b21621aec927ea74ece5e3d2e55780e5b650eb4e2278a960a543d5a83c18148117156ee07e4ab717ba48708d299db33c61d543d7e1220e6e9cc
-  data.tar.gz: e7047f922618c9efaf666e6ad2dd46a80381349c0fd9c038d25cfd462fdf076e736fea865d5abfac2684f60f5ebd44353ce2acc0ee736dc9eed6b7a0105ab7ee
+  metadata.gz: f2df0a83caef1ff642f07b7afa9fcdb2ae70c7d25f8f848bdcefe0f405d4b7ca0c22b92e9fdb11aa7b9ebc2f424fc75a92cbd709b4ab84e5033fcda54b102963
+  data.tar.gz: ab9a2b334311157f842e3a62e2effe555df9d1c6a860c38e48244f1a8c50465cf3a8e8c0c1cfa9da3f4b76edec390fce4f478b978a337ea8f02d0684cee719ef

data/.gitignore

@@ -11,3 +11,4 @@
 .env
 .log
 *.gem
+*.swp

data/Changelog.md

@@ -0,0 +1,14 @@
+1.0.0
+
+Use 'proper' date format for ExactOnline
+Don't add quotes to integers when filtering
+Raise error on invalid request
+Add project and time tracking functionality
+
+0.2.0
+
+First official release, used within Hoppinger, basic functionality and resources Hoppinger needed.
+
+0.1.0
+
+Dev release

data/README.md

@@ -82,79 +82,75 @@ unless Elmas.authorized?
 end
 ```
 
-## GET, PUT, POST requests
+## Accessing the API
 
-For any of the following requests (GET, PUT, POST), to get the results do the following. (the exact API always returns a List)
-```ruby
-contact = Elmas::Contact.new(id: "23445")
-response = contact.find
-puts response.first
-# Prints something like this
-# [<Elmas::Contact:0x007fb0a55782f0 @attributes={:__metadata=>{"uri"=>"https://start.exactonline.nl/api/v1/797636/crm/Contacts(guid'23445')", "type"=>"Exact.Web.Api.Models.Contact"}, :id=>"23445", :person=>"88380fa4-97bc-4ddf-90e3-b0e7befb112c"}>
-
-contact = Elmas::Contact.new.find_all
-response = contact.find_all
-puts response.results
-# Prints something like this
-# [<Elmas::Contact:0x007fb0a55782f0 @attributes={:__metadata=>{"uri"=>"https://start.exactonline.nl/api/v1/797636/crm/Contacts(guid'23445')", "type"=>"Exact.Web.Api.Models.Contact"}, :id=>"23445", :person=>"88380fa4-97bc-4ddf-90e3-b0e7befb112c"}>, <Elmas::Contact:0x007fb0a55782f0 @attributes={:__metadata=>{"uri"=>"https://start.exactonline.nl/api/v1/797636/crm/Contacts(guid'23445')", "type"=>"Exact.Web.Api.Models.Contact"}, :id=>"23445", :person=>"88380fa4-97bc-4ddf-90e3-b0e7befb112c"}>]
-```
+We can retrieve data from the API using the following syntax.
 
-To find a contact
+The query will return an `Elmas::ResultSet` which contains up to 60 records and
+a method to retrieve the next page of results. Unfortunately the ExactOnline API
+does not allow us to retrieve a specific page or define how many records we want
+to retrieve at a time.
 
 ```ruby
-contact = Elmas::Contact.new(id: "23445")
-contact.find
-# path = /crm/Contacts(guid'23445')
-```
+# Query the API and return an Elmas::ResultSet
+accounts = Elmas::Account.new.find_all
 
-To find a contact with specific filters
-```ruby
-contact = Elmas::Contact.new(first_name: "Karel", id: "23")
-contact.find_by(filters: [:first_name])
-# path = /crm/Contacts?$filter=first_name eq 'Karel'
+# Return an array of accounts
+accounts.records
 ```
 
-To find contacts with an order and a filter
+If the query results in more than 60 records the next set can be retrieved using
+the `next_page` method.
+
 ```ruby
-contact = Elmas::Contact.new(first_name: "Karel")
-contact.find_by(filters: [:first_name], order_by: :first_name)
-# path = /crm/Contacts?$order_by=first_name&$filter=first_name eq 'Karel'
+# Return an Elmas::ResultSet containing the next page's records
+accounts.next_page
 ```
 
-To find contacts with an order, a filter and selecting relationships
+### Filter results
+
+Filtering result sets can be done by adding attributes to the initializer and then
+using `find_by`. Filters accept a single value or an array of values.
+
+So far only 'eq' has been implemented, so only direct matches will be returned.
+
 ```ruby
-contact = Elmas::Contact.new(first_name: "Karel")
-contact.find_by(filters: [:first_name], order_by: :first_name, select: [:last_name])
-# path = /crm/Contacts?$select=last_name&$order_by=first_name&$filter=first_name eq 'Karel'
+# Find the account with code 123
+accounts = Elmas::Account.new(code: '123').find_by(filter: [:code])
+
+# Find the accounts with code 123 and 345
+accounts = Elmas::Account.new(code: ['123', '345']).find_by(filter: [:code])
 ```
 
-So with find_by you can combine Filters, Select and OrderBy. For more information on this way of selecting data look here http://www.odata.org/
-There's also a method find_all, which does a get without filters. You can however set the select and order by params.
+Results can be sorted in the same way
 
-To find all contacts
 ```ruby
-contact = Elmas::Contact.new
-contact.find_all
-# path = /crm/Contacts
+# Return all accounts sorted by first name
+accounts = Elmas::Account.new.find_all(order_by: :first_name)
 ```
 
-To find all contacts and order by first_name
+Filters and sorting can also be combined
+
 ```ruby
-contact = Elmas::Contact.new
-contact.find_all(order_by: :first_name)
-# path = /crm/Contacts?$order_by=first_name
+# Return accounts with code 123 and 345 sorted by first name
+accounts = Elmas::Account.new(code: ['123', '345']).find_by(filter: [:code], order_by: :first_name)
 ```
 
-To find all contacts and select invoices and items
+To find an individual record by its ID the `find` method can be used
+
 ```ruby
-contact = Elmas::Contact.new
-contact.find_all(select: [:last_name, :first_name])
-# path = /crm/Contacts?$select=last_name,first_name
+# Return the account with guid
+account = Elmas::Account.new(id: '9e3a078e-55dc-40f4-a490-1875400a3e10').find
 ```
 
-To create a new contact
+For more information on this way of selecting data look here http://www.odata.org/
+
+### Creating new records
+
+Use the initializer method followed by 'save' to create a new record:
 
 ```ruby
+# Create a new contact
 contact = Elmas::Contact.new(first_name: "Karel", last_name: "Appel", account: "8d87c8c5-f1c6-495c-b6af-d5ba396873b5"  )
 contact.save
 ```

data/lib/elmas/oauth.rb

@@ -20,16 +20,14 @@ module Elmas
 
     def authorized?
       # Do a test call, return false if 401 or any error code
-      begin
-        response = get("/Current/Me", no_division: true)
-      rescue BadRequestException => e
-        Elmas.error "Not yet authorized"
-        return false
-      end
+      get("/Current/Me", no_division: true)
+    rescue BadRequestException
+      Elmas.error "Not yet authorized"
+      return false
     end
 
     def authorize_division
-      get("/Current/Me", no_division: true).first.current_division
+      get("/Current/Me", no_division: true).results.first.current_division
     end
 
     def auto_authorize

data/lib/elmas/parser.rb

@@ -5,28 +5,30 @@ module Elmas
     def initialize(json)
       @parsed_json = JSON.parse(json)
     rescue JSON::ParserError => e
-      Elmas.error 'There was an error parsing the response'
+      Elmas.error "There was an error parsing the response"
       Elmas.error "#{e.class}: #{e.message}"
       @error_message = "#{e.class}: #{e.message}"
     end
 
     def results
-      result['results'] if result && result['results']
+      result["results"] if result && result["results"]
     end
 
     def metadata
-      result['__metadata'] if result && result['__metadata']
+      result["__metadata"] if result && result["__metadata"]
     end
 
     def result
-      parsed_json['d']
+      parsed_json["d"]
+    end
+
+    def next_page_url
+      result && result["__next"]
     end
 
     def error_message
       @error_message ||= begin
-        if parsed_json['error']
-          parsed_json['error']['message']['value']
-        end
+        parsed_json["error"]["message"]["value"] if parsed_json["error"]
       end
     end
 

data/lib/elmas/request.rb

@@ -24,9 +24,11 @@ module Elmas
     private
 
     def build_path(path, options)
-      path = "#{division}/#{path}" unless options[:no_division]
-      path = "#{endpoint}/#{path}" unless options[:no_endpoint]
-      path = "#{options[:url] || base_url}/#{path}"
+      unless options[:use_raw_path]
+        path = "#{division}/#{path}" unless options[:no_division]
+        path = "#{endpoint}/#{path}" unless options[:no_endpoint]
+        path = "#{options[:url] || base_url}/#{path}"
+      end
       path
     end
 

data/lib/elmas/resource.rb

@@ -40,7 +40,7 @@ module Elmas
     def find
       return nil unless id?
       response = get(uri([:id]))
-      response.result if response
+      response.results.first if response
     end
 
     # Normally use the url method (which applies the filters) but sometimes you only want to use the base path or other paths

data/lib/elmas/resources/aging_receivables_list.rb

@@ -0,0 +1,32 @@
+module Elmas
+  # We can use the AgingReceivablesList to change the status of SalesInvoices from
+  # Open to 'Verwerkt' while at the same time sending a PDF of the invoice to the
+  # end user by e-mail.
+  #
+  # This endpoint only supports the POST method.
+  #
+  class AgingReceivablesList
+    include Elmas::Resource
+
+    def valid_actions
+      [:get]
+    end
+
+    def base_path
+      "financial/AgingReceivablesLists"
+    end
+
+    def mandatory_attributes
+      []
+    end
+
+    # https://start.exactonline.nl/docs/HlpRestAPIResourcesDetails.aspx?name=SalesInvoiceAgingReceivablesLists
+    def other_attributes
+      [
+        :account_id, :account_code, :account_name, :age_group1, :age_group1_amount, :age_group1_description,
+        :age_group2, :age_group2_amount, :age_group2_description, :age_group3, :age_group3_amount, :age_group3_description,
+        :age_group4, :age_group4_amount, :age_group4_description, :currency_code, :total_amount
+      ]
+    end
+  end
+end

data/lib/elmas/resources/layout.rb

@@ -0,0 +1,24 @@
+module Elmas
+  class Layout
+    include Elmas::Resource
+
+    def valid_actions
+      [:get]
+    end
+
+    def base_path
+      "salesinvoice/Layouts"
+    end
+
+    def mandatory_attributes
+      []
+    end
+
+    def other_attributes
+      [
+        :id, :created, :creator, :creator_full_name, :division,
+        :modified, :modifier, :modifier_full_name, :subject, :type
+      ]
+    end
+  end
+end

data/lib/elmas/resources/printed_sales_invoice.rb

@@ -0,0 +1,35 @@
+module Elmas
+  # We can use the PrintedSalesInvoice to change the status of SalesInvoices from
+  # Open to 'Verwerkt' while at the same time sending a PDF of the invoice to the
+  # end user by e-mail.
+  #
+  # This endpoint only supports the POST method.
+  #
+  class PrintedSalesInvoice
+    include Elmas::Resource
+
+    def valid_actions
+      [:post]
+    end
+
+    def base_path
+      "salesinvoice/PrintedSalesInvoices"
+    end
+
+    def mandatory_attributes
+      [:invoice_ID]
+    end
+
+    # https://start.exactonline.nl/docs/HlpRestAPIResourcesDetails.aspx?name=SalesInvoicePrintedSalesInvoices
+    def other_attributes
+      [
+        :division, :document, :document_creation_error, :document_creation_success,
+        :document_layout, :email_creation_error, :email_creation_success, :email_layout,
+        :extra_text, :invoice_date, :postbox_message_creation_error,
+        :postbox_message_creation_success, :postbox_sender, :reporting_period,
+        :reporting_year, :send_email_to_customer, :send_invoice_to_customer_postbox,
+        :send_output_based_on_account
+      ]
+    end
+  end
+end

data/lib/elmas/resources/receivables_list.rb

@@ -0,0 +1,32 @@
+module Elmas
+  # We can use the AgingReceivablesList to change the status of SalesInvoices from
+  # Open to 'Verwerkt' while at the same time sending a PDF of the invoice to the
+  # end user by e-mail.
+  #
+  # This endpoint only supports the POST method.
+  #
+  class ReceivablesList
+    include Elmas::Resource
+
+    def valid_actions
+      [:get]
+    end
+
+    def base_path
+      "read/financial/ReceivablesList"
+    end
+
+    def mandatory_attributes
+      []
+    end
+
+    # https://start.exactonline.nl/docs/HlpRestAPIResourcesDetails.aspx?name=ReadFinancialReceivablesList
+    def other_attributes
+      [
+        :description, :hid, :account_code, :account_id, :account_name, :amount, :amount_in_transit,
+        :currency_code, :description, :due_date, :entry_number, :id, :invoice_date, :invoice_number,
+        :journal_code, :journal_description, :your_ref
+      ]
+    end
+  end
+end

data/lib/elmas/response.rb

@@ -7,10 +7,7 @@ module Elmas
 
     def initialize(response)
       @response = response
-      if fail?
-        log_error
-        raise BadRequestException.new(@response, parsed)
-      end
+      raise_and_log_error if fail?
     end
 
     def success?
@@ -25,33 +22,12 @@ module Elmas
       Parser.new(body)
     end
 
-    def results
-      results = []
-      if parsed.results
-        parsed.results.each do |attributes|
-          klass = resolve_class
-          results << klass.send(:new, attributes)
-        end
-      end
-      results
-    end
-
     def result
-      klass = resolve_class
-      klass.send(:new, parsed.result)
+      Elmas::ResultSet.new(parsed)
     end
 
-    def first
-      results ? results.first : result
-    end
-
-    def type
-      if parsed.metadata
-        c_type = parsed.metadata["type"]
-      elsif parsed.results.any?
-        c_type = parsed.results.first["__metadata"]["type"]
-      end
-      c_type.split(".").last
+    def results
+      Elmas::ResultSet.new(parsed)
     end
 
     def status
@@ -85,12 +61,9 @@ module Elmas
 
     private
 
-    def resolve_class
-      constant_name = Utils.modulize(type)
-      return Object.const_get(constant_name)
-    rescue NameError
-      Elmas.info("Unknown resource encountered, proceed as usual but further resource details might have to be implemented")
-      return Class.new { include Elmas::Resource }
+    def raise_and_log_error
+      log_error
+      fail BadRequestException.new(@response, parsed)
     end
   end
 end

data/lib/elmas/result_set.rb

@@ -0,0 +1,55 @@
+module Elmas
+  class ResultSet
+    attr_reader :records
+
+    def initialize(parsed_response)
+      @parsed_response = parsed_response
+
+      if @parsed_response.results
+        @records = @parsed_response.results.map do |attributes|
+          resource_class.send(:new, attributes)
+        end
+      else
+        @records = [resource_class.send(:new, @parsed_response.result)]
+      end
+    end
+
+    def next_page
+      return unless next_page_url
+      next_page = Elmas.get(next_page_url, use_raw_path: true)
+      return unless next_page
+
+      response = Elmas::Response.new(next_page)
+      response.results
+    end
+
+    def first
+      records.first
+    end
+
+    protected
+
+    def next_page_url
+      @parsed_response.next_page_url
+    end
+
+    def type
+      if @parsed_response.metadata
+        c_type = @parsed_response.metadata["type"]
+      elsif @parsed_response.results.any?
+        c_type = @parsed_response.results.first["__metadata"]["type"]
+      end
+      c_type.split(".").last
+    end
+
+    def resource_class
+      @resource_class ||= begin
+        constant_name = Utils.modulize(type)
+        Object.const_get(constant_name)
+      rescue NameError
+        Elmas.info("Unknown resource encountered, proceed as usual but further resource details might have to be implemented")
+        Class.new { include Elmas::Resource }
+      end
+    end
+  end
+end

data/lib/elmas/uri.rb

@@ -18,21 +18,36 @@ module Elmas
         uri
       end
 
-      # ?$filter=ID eq guid'#{id}'
-      def id_filter
-        ["$filter", "ID eq guid'#{id}'"]
+      def base_filter(attribute)
+        values = @attributes[attribute]
+        values = [values] unless values.is_a?(Array)
+
+        filters = values.map do |value|
+          "#{query_attribute(attribute)} eq #{sanitize_value(value)}"
+        end
+
+        ["$filter", filters.join(" or ")]
       end
 
-      def base_filter(attribute)
+      # Sanitize an attribute in symbol format to the ExactOnline style
+      def query_attribute(attribute)
         if attribute == :id
-          return id_filter
+          attribute.to_s.upcase
         else
-          if @attributes[attribute].is_a?(Fixnum)
-            value = @attributes[attribute]
+          Utils.camelize(attribute)
+        end
+      end
+
+      # Convert a value to something usable in an ExactOnline request
+      def sanitize_value(value)
+        if value.is_a?(String)
+          if value =~ /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/
+            "guid'#{value}'"
           else
-            value = "'#{@attributes[attribute]}'"
+            "'#{value}'"
           end
-          return ["$filter", "#{Utils.camelize(attribute)} eq #{value}"]
+        else
+          value
         end
       end
 

data/lib/elmas/version.rb

@@ -1,6 +1,6 @@
 module Elmas
   class Version
-    MAJOR = 1
+    MAJOR = 2
     MINOR = 0
     PATCH = 0
 

data/lib/elmas.rb

@@ -5,17 +5,22 @@ require "elmas/response"
 require "elmas/client"
 require "elmas/log"
 require "elmas/resource"
+require "elmas/result_set"
 require "elmas/sanitizer"
+require "elmas/resources/aging_receivables_list"
+require "elmas/resources/receivables_list"
 require "elmas/resources/shared_sales_attributes"
 require "elmas/resources/base_entry_line"
 require "elmas/resources/bank_entry"
 require "elmas/resources/bank_entry_line"
 require "elmas/resources/contact"
 require "elmas/resources/sales_invoice"
+require "elmas/resources/sales_invoice_line"
+require "elmas/resources/printed_sales_invoice"
+require "elmas/resources/layout"
 require "elmas/resources/journal"
 require "elmas/resources/item"
 require "elmas/resources/item_group"
-require "elmas/resources/sales_invoice_line"
 require "elmas/resources/account"
 require "elmas/resources/gl_account"
 require "elmas/resources/sales_entry"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: elmas
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Marthyn
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-12-01 00:00:00.000000000 Z
+date: 2015-12-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -223,6 +223,7 @@ files:
 - ".rspec"
 - ".rubocop.yml"
 - ".travis.yml"
+- Changelog.md
 - Gemfile
 - Guardfile
 - LICENSE
@@ -243,6 +244,7 @@ files:
 - lib/elmas/request.rb
 - lib/elmas/resource.rb
 - lib/elmas/resources/account.rb
+- lib/elmas/resources/aging_receivables_list.rb
 - lib/elmas/resources/bank_entry.rb
 - lib/elmas/resources/bank_entry_line.rb
 - lib/elmas/resources/base_entry_line.rb
@@ -255,10 +257,13 @@ files:
 - lib/elmas/resources/item.rb
 - lib/elmas/resources/item_group.rb
 - lib/elmas/resources/journal.rb
+- lib/elmas/resources/layout.rb
 - lib/elmas/resources/mailbox.rb
+- lib/elmas/resources/printed_sales_invoice.rb
 - lib/elmas/resources/project.rb
 - lib/elmas/resources/purchase_entry.rb
 - lib/elmas/resources/purchase_entry_line.rb
+- lib/elmas/resources/receivables_list.rb
 - lib/elmas/resources/sales_entry.rb
 - lib/elmas/resources/sales_entry_line.rb
 - lib/elmas/resources/sales_invoice.rb
@@ -271,6 +276,7 @@ files:
 - lib/elmas/resources/transaction_line.rb
 - lib/elmas/resources/vat_code.rb
 - lib/elmas/response.rb
+- lib/elmas/result_set.rb
 - lib/elmas/sanitizer.rb
 - lib/elmas/uri.rb
 - lib/elmas/utils.rb