sugarcrm 0.9.12 → 0.9.13

data/README.rdoc

@@ -38,7 +38,10 @@ A less clunky way to interact with SugarCRM via REST.
   SugarCRM.modules
 
   # Retrieve a User by user_name
-  SugarCRM::User.find_by_user_name("admin")
+  users = SugarCRM::User.find_by_user_name("admin")
+  
+  # Return a User instance's SugarCRM URL (also works for any other module instance)
+  users.url
   
   # Update a User's title
   u = SugarCRM::User.find_by_first_name_and_last_name("Will", "Westin")
@@ -95,6 +98,9 @@ A less clunky way to interact with SugarCRM via REST.
   a.contacts.delete(c)
   a.save # or a.contacts.save
   
+  # Retrieve the number of accounts in CRM with 'Inc' in their name
+  SugarCRM::Account.count(:conditions => {:name => "LIKE '%Inc'"})
+  
   # Look up the Case with the smallest case number
   SugarCRM::Case.first({
     :order_by => 'case_number'
@@ -116,6 +122,12 @@ A less clunky way to interact with SugarCRM via REST.
   SugarCRM::Account.all({
     :conditions => { :name => "LIKE '%Fund%'" } # note that SQL operators must be uppercase
   })
+
+  # Use block to iterate over results: print all account names
+  SugarCRM::Account.all{|a| puts a.name } # note: this method will be much quicker than SugarCRM::Account.all.each{|a| puts a.name }
+                                          # because records are passed to the block as they get fetched from SugarCRM (whereas `each`
+                                          # will fetch all records, and only then pass them to the block). This will make a major difference
+                                          # in resource use and execution time if you're dealing with many records.
   
   # Look up the fields for a given module
   SugarCRM::Module.find("Accounts").fields
@@ -149,7 +161,9 @@ Note: this gem requires Rails 3 as it depends on Active Support >= 3.
 4. Run `rails g sugarcrm:config`
 5. Edit the configuration file in `config/sugarcrm.yml` to match your environment
 
-Example app here: https://github.com/davidsulc/sugar_on_rails_basic
+Example apps:
+* https://github.com/davidsulc/sugar_on_rails_basic
+* https://github.com/davidsulc/dev_zone_basic_rails_app
 
 == USING A CONFIGURATION FILE
 

data/Rakefile

@@ -18,7 +18,7 @@ Jeweler::Tasks.new do |gem|
   gem.homepage = "http://github.com/chicks/sugarcrm"
   gem.authors = ["Carl Hicks", "David Sulc"]
   gem.executables = ['sugarcrm']
-  gem.files = FileList['./lib/**/*', './*'].exclude("*.lock").to_a
+  gem.files = FileList['./lib/**/*', './*'].exclude("*.lock", "*.tmproj").to_a
 end
 Jeweler::RubygemsDotOrgTasks.new
 

data/VERSION

@@ -1 +1 @@
-0.9.12
+0.9.13

data/lib/sugarcrm/attributes/attribute_methods.rb

@@ -145,7 +145,7 @@ module SugarCRM; module AttributeMethods
   # sets the id if it's a new record
   def save_modified_attributes!
     # Complain if we aren't valid
-    raise InvalidRecord, errors.to_a.join(", ") if !valid?
+    raise InvalidRecord, @errors.full_messages.join(", ") unless valid?
     # Send the save request
     response = self.class.session.connection.set_entry(self.class._module.name, serialize_modified_attributes)
     # Complain if we don't get a parseable response back

data/lib/sugarcrm/attributes/attribute_validations.rb

@@ -1,11 +1,30 @@
 module SugarCRM; module AttributeValidations
   # Checks to see if we have all the neccessary attributes
   def valid?
-    @errors = Set.new
+    @errors = ActiveSupport::HashWithIndifferentAccess.new
+    
     self.class._module.required_fields.each do |attribute|
       valid_attribute?(attribute)
     end
-    @errors.length == 0
+    
+    # for rails compatibility
+    def @errors.full_messages
+      # After removing attributes without errors, flatten the error hash, repeating the name of the attribute before each message:
+      # e.g. {'name' => ['cannot be blank', 'is too long'], 'website' => ['is not valid']}
+      # will become 'name cannot be blank, name is too long, website is not valid
+      self.inject([]){|memo, obj| memo.concat(obj[1].inject([]){|m, o| m << "#{obj[0].to_s.humanize} #{o}" })}
+    end
+    
+    # Rails needs each attribute to be present in the error hash (if the attribute has no error, it has [] as a value)
+    # Redefine the [] method for the errors hash to return [] instead of nil is the hash doesn't contain the key
+    class << @errors
+      alias :old_key_lookup :[]
+      def [](key)
+        old_key_lookup(key) || Array.new
+      end
+    end
+    
+    @errors.size == 0
   end
   
   protected
@@ -21,7 +40,7 @@ module SugarCRM; module AttributeValidations
       validate_class_for(attribute, [Fixnum, Float])
     else 
       if @attributes[attribute].blank?
-        @errors.add "#{attribute} cannot be blank"
+        add_error(attribute, "cannot be blank")
       end
     end
   end
@@ -30,8 +49,14 @@ module SugarCRM; module AttributeValidations
   # returns true if they match, otherwise adds an entry to the @errors collection, and returns false
   def validate_class_for(attribute, class_array)
     return true if class_array.include? @attributes[attribute].class
-    @errors.add "#{attribute} must be a #{class_array.join(" or ")} object (not #{@attributes[attribute].class})"
+    add_error(attribute, "must be a #{class_array.join(" or ")} object (not #{@attributes[attribute].class})")
     false  
   end
   
+  # Add an error to the hash
+  def add_error(attribute, message)
+    @errors[attribute] ||= []
+    @errors[attribute] = @errors[attribute] << message unless @errors[attribute].include? message
+    @errors
+  end
 end; end

data/lib/sugarcrm/base.rb

@@ -25,7 +25,7 @@ module SugarCRM; class Base
   attr :errors, true
 
   class << self # Class methods
-    def find(*args)
+    def find(*args, &block)
       options = args.extract_options!
       options = {:order_by => 'date_entered'}.merge(options)
       validate_find_options(options)
@@ -35,39 +35,44 @@ module SugarCRM; class Base
           find_initial(options)
         when :last
           begin
-            options[:order_by] = reverse_order_clause(options[:order_by])
+            options[:order_by] = reverse_order_clause(options[:order_by].to_s)
           rescue Exception => e
             raise
           end
           find_initial(options)
         when :all
-          Array.wrap(find_every(options)).compact
+          Array.wrap(find_every(options, &block)).compact
         else
-          find_from_ids(args, options)
+          find_from_ids(args, options, &block)
       end
     end
   
     # return the connection to the correct SugarCRM server (there can be several)
     def connection
-      self.parent.session.connection
+      self.session.connection
+    end
+    
+    def count(options={})
+      query = query_from_options(options)
+      connection.get_entries_count(self._module.name, query, options)['result_count'].to_i
     end
 
     # A convenience wrapper for <tt>find(:first, *args)</tt>. You can pass in all the
     # same arguments to this method as you can to <tt>find(:first)</tt>.
-    def first(*args)
-      find(:first, *args)
+    def first(*args, &block)
+      find(:first, *args, &block)
     end
 
     # A convenience wrapper for <tt>find(:last, *args)</tt>. You can pass in all the
     # same arguments to this method as you can to <tt>find(:last)</tt>.
-    def last(*args)
-      find(:last, *args)
+    def last(*args, &block)
+      find(:last, *args, &block)
     end
 
     # This is an alias for find(:all).  You can pass in all the same arguments to this method as you can
     # to find(:all)
-    def all(*args)
-      find(:all, *args)
+    def all(*args, &block)
+      find(:all, *args, &block)
     end
     
     # Creates an object (or multiple objects) and saves it to SugarCRM if validations pass.
@@ -102,11 +107,11 @@ module SugarCRM; class Base
         object
       end
     end
-
   end
 
   # Creates an instance of a Module Class, i.e. Account, User, Contact, etc.
   def initialize(attributes={}, &block)
+    @errors = {}
     @modified_attributes = {}
     merge_attributes(attributes.with_indifferent_access)
     clear_association_cache
@@ -131,7 +136,7 @@ module SugarCRM; class Base
   # Saves the current object, checks that required fields are present.
   # returns true or false
   def save
-    return false if !changed?
+    return false if !(new_record? || changed?)
     return false if !valid?
     begin
       save!
@@ -156,6 +161,12 @@ module SugarCRM; class Base
     params[:deleted]= {:name => "deleted", :value => "1"}
     @attributes[:deleted] = (self.class.connection.set_entry(self.class._module.name, params).class == Hash)
   end
+  alias :destroy :delete
+  
+  # Returns if the record is persisted, i.e. it’s not a new record and it was not destroyed
+  def persisted?
+    !(new_record? || destroyed?)
+  end
   
   # Reloads the record from SugarCRM
   def reload!
@@ -178,16 +189,39 @@ module SugarCRM; class Base
   end
   alias :eql? :==
   
-  def update_attribute(name, value)
+  def update_attribute!(name, value)
     self.send("#{name}=".to_sym, value)
-    self.save
+    self.save!
   end
   
-  def update_attributes(attributes)
+  def update_attribute(name, value)
+    begin
+      update_attribute!(name, value)
+    rescue
+      return false
+    end
+    true
+  end
+  
+  def update_attributes!(attributes)
     attributes.each do |name, value|
       self.send("#{name}=".to_sym, value)
     end
-    self.save
+    self.save!
+  end
+  
+  def update_attributes(attributes)
+    begin
+      update_attributes!(attributes)
+    rescue
+      return false
+    end
+    true
+  end
+  
+  # Returns the URL (in string format) where the module instance is available in CRM
+  def url
+    "#{SugarCRM.session.config[:base_url]}/index.php?module=#{self.class._module}&action=DetailView&record=#{self.id}"
   end
     
   # Delegates to id in order to allow two records of the same type and id to work with something like:
@@ -197,7 +231,7 @@ module SugarCRM; class Base
   end
 
   def pretty_print(pp)
-    pp.text self.inspect, 0
+    pp.text self.inspect.to_s, 0
   end
 
   def attribute_methods_generated?
@@ -208,6 +242,31 @@ module SugarCRM; class Base
     self.class.association_methods_generated
   end
   
+  def to_key
+    new_record? ? nil : [ id ]
+  end
+  
+  def to_param
+    id.to_s
+  end
+  
+  def is_a?(klass)
+    superclasses.include? klass
+  end
+  alias :kind_of? :is_a?
+  alias :=== :is_a?
+  
+  private
+  def superclasses
+    return @superclasses if @superclasses
+    @superclasses = [self.class]
+    current_class = self.class
+    while current_class.respond_to? :superclass
+      @superclasses << (current_class = current_class.superclass)
+    end
+    @superclasses
+  end
+  
   Base.class_eval do
     extend  FinderMethods::ClassMethods
     include AttributeMethods

data/lib/sugarcrm/connection/request.rb

@@ -21,6 +21,10 @@ module SugarCRM; class Request
     self
   end
   
+  def bytesize
+    self.to_s.bytesize
+  end
+  
   def length
     self.to_s.length
   end

data/lib/sugarcrm/connection/response.rb

@@ -80,6 +80,7 @@ module SugarCRM; class Response
   # Takes a hash like { "first_name" => {"name" => "first_name", "value" => "John"}}
   # And flattens it into {"first_name" => "John"}
   def flatten(list)
+    raise ArgumentError, list[0]['value'] if list[0] && list[0]['name'] == 'warning'
     raise ArgumentError, 'method parameter must respond to #each_pair' unless list.respond_to? :each_pair
     flat_list = {}
     list.each_pair do |k,v|

data/lib/sugarcrm/connection_pool.rb

@@ -11,7 +11,7 @@ module SugarCRM; class ConnectionPool
     # The mutex used to synchronize pool access
     @connection_mutex = Monitor.new
     @queue = @connection_mutex.new_cond
-    @timeout = config_timeout || 5
+    @timeout = config_timeout || 10
     
     # default max pool size to 5
     @size = config_pool_size || default_pool_size

data/lib/sugarcrm/finders/finder_methods.rb

@@ -8,7 +8,7 @@ module SugarCRM; module FinderMethods
         result
       end
   
-      def find_from_ids(ids, options)
+      def find_from_ids(ids, options, &block)
         expects_array = ids.first.kind_of?(Array)
         return ids.first if expects_array && ids.first.empty?
 
@@ -21,7 +21,7 @@ module SugarCRM; module FinderMethods
             result = find_one(ids.first, options)
             expects_array ? [ result ] : result
           else
-            find_some(ids, options)
+            find_some(ids, options, &block)
         end
       end
   
@@ -34,7 +34,7 @@ module SugarCRM; module FinderMethods
         end
       end
     
-      def find_some(ids, options)
+      def find_some(ids, options, &block)
         result = connection.get_entries(self._module.name, ids, {:fields => self._module.fields.keys})
 
         # Determine expected size from limit and offset, not just ids.size.
@@ -51,67 +51,73 @@ module SugarCRM; module FinderMethods
         end
 
         if result.size == expected_size
+          if block_given?
+            result.each{|r|
+              yield r
+            }
+          end
           result
         else
           raise RecordNotFound, "Couldn't find all #{name.pluralize} with IDs (#{ids_list})#{conditions} (found #{result.size} results, but was looking for #{expected_size})"
         end
       end
     
-      def find_every(options)
-        find_by_sql(options)
+      def find_every(options, &block)
+        find_by_sql(options, &block)
       end
-        
-      def find_by_sql(options)
-        # SugarCRM REST API has a bug where, when :limit and :offset options are passed simultaneously, :limit is considered to be the smallest of the two, and :offset is the larger
-        # in addition to allowing querying of large datasets while avoiding timeouts,
+      
+      # the number of records we retrieve with each query
+      # it is kept small to avoid timeout issues
+      SLICE_SIZE = 5
+      SLICE_SIZE.freeze
+      # results accumulator stores the results we have fetched so far, recursively
+      def find_by_sql(options, results_accumulator=nil, &block)
+        # SugarCRM REST API has a bug where, when :limit and :offset options are passed simultaneously,
+        # :limit is considered to be the smallest of the two, and :offset is the larger
+        # In addition to allowing querying of large datasets while avoiding timeouts (by fetching results in small slices),
         # this implementation fixes the :limit - :offset bug so that it behaves correctly
+        
+        offset = options[:offset].to_i >= 1 ? options[:offset].to_i : nil
+        
+        # if many results are requested (i.e. multiple result slices), we call this function recursively
+        # this array keeps track of which slice we are retrieving (by updating the :offset and :limit options)
         local_options = {}
-        options.keys.each{|k|
-          local_options[k] = options[k]
-        }
-        local_options.delete(:offset) if local_options[:offset] == 0
-      
-        # store the number of records wanted by user, as we'll overwrite :limit option to obtain several slices of records (to avoid timeout issues)
-        nb_to_fetch = local_options[:limit]
-        nb_to_fetch = nb_to_fetch.to_i if nb_to_fetch
-        offset_value = local_options[:offset] || 10 # arbitrary value, must be bigger than :limit used (see comment above)
-        offset_value = offset_value.to_i
-        offset_value.freeze
-        initial_limit = nb_to_fetch.nil?  ? offset_value : [offset_value, nb_to_fetch].min # how many records should be fetched on first pass
         # ensure results are ordered so :limit and :offset option behave in a deterministic fashion
-        local_options = { :order_by => :id }.merge(local_options)
-        local_options.update(:limit => initial_limit) # override original argument
-      
-        # get first slice of results
-        # note: to work around a SugarCRM REST API bug, the :limit option must always be smaller than the :offset option
-        # this is the reason this first query is separate (not in the loop): the initial query has a larger limit, so that we can then use the loop
-        # with :limit always smaller than :offset
-        results = connection.get_entry_list(self._module.name, query_from_options(local_options), local_options)
-        return nil unless results
-        results = Array.wrap(results)
-      
-        limit_value = [5, offset_value].min # arbitrary value, must be smaller than :offset used (see comment above)
-        limit_value.freeze
-        local_options = { :order_by => :id }.merge(local_options)
-        local_options.update(:limit => limit_value)
-      
-        # a portion of the results has already been queried
-        # update or set the :offset value to reflect this
-        local_options[:offset] ||= results.size
-        local_options[:offset] += offset_value
-      
-        # continue fetching results until we either
-        # a) have as many results as the user wants (specified via the original :limit option)
-        # b) there are no more results matching the criteria
-        while result_slice = connection.get_entry_list(self._module.name, query_from_options(local_options), local_options)
-          results.concat(Array.wrap(result_slice))
-          # make sure we don't return more results than the user requested (via original :limit option)
-          if nb_to_fetch && results.size >= nb_to_fetch
-            return results.slice(0, nb_to_fetch)
-          end
-          local_options[:offset] += local_options[:limit] # update :offset as we get more records
+        local_options[:order_by] = :id unless options[:order_by]
+        
+        # we must ensure limit <= offset (due to bug mentioned above)
+        if offset
+          local_options[:limit] = [offset.to_i, SLICE_SIZE].min
+          local_options[:offset] = offset if offset
+        else
+          local_options[:limit] = options[:limit] ? [options[:limit].to_i, SLICE_SIZE].min : SLICE_SIZE
+        end
+        local_options[:limit] = [local_options[:limit], options[:limit]].min if options[:limit] # don't retrieve more records than required
+        local_options = options.merge(local_options)
+        
+        query = query_from_options(local_options)
+        result_slice = connection.get_entry_list(self._module.name, query, local_options)
+        return results_accumulator unless result_slice
+        
+        result_slice_array = Array.wrap(result_slice)
+        if block_given?
+          result_slice_array.each{|r| yield r }
+        else
+          results_accumulator = [] unless results_accumulator
+          results_accumulator = results_accumulator.concat(result_slice_array)
+        end
+        
+        # adjust options to take into account records that were already retrieved
+        updated_options = {:offset => options[:offset].to_i + result_slice_array.size}
+        updated_options[:limit] = (options[:limit] ? options[:limit] - result_slice_array.size : nil)
+        updated_options = options.merge(updated_options)
+        
+        # have we retrieved all the records?
+        if (updated_options[:limit] && updated_options[:limit] < 1) || local_options[:limit] > result_slice_array.size
+          return results_accumulator
+        else
+          find_by_sql(updated_options, results_accumulator, &block)
         end
-        results
       end
 
       def query_from_options(options)

data/lib/sugarcrm/session.rb

@@ -16,7 +16,7 @@ module SugarCRM; class Session
     
     setup_connection
     register_namespace
-    connect_and_add_session
+    connect(@config[:base_url], @config[:username], @config[:password], @config[:options])
   end
   
   # Creates a new session from the credentials present in a file
@@ -66,6 +66,7 @@ module SugarCRM; class Session
     SugarCRM::Module.deregister_all(self)
     @connection_pool = SugarCRM::ConnectionPool.new(self)
     SugarCRM::Module.register_all(self)
+    SugarCRM.add_session(self)
     load_extensions
     true
   end
@@ -195,11 +196,6 @@ module SugarCRM; class Session
   def load_extensions
     self.class.validate_path @extensions_path
     Dir[File.join(@extensions_path, '**', '*.rb').to_s].each { |f| load(f) }
-  end  
-  
-  def connect_and_add_session
-    connect(@config[:base_url], @config[:username], @config[:password], @config[:options])
-    SugarCRM.add_session(self)
   end
   
   # Returns hash containing only keys/values relating to connection pool options. These are removed from parameter hash.

data/sugarcrm.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{sugarcrm}
-  s.version = "0.9.12"
+  s.version = "0.9.13"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Carl Hicks", "David Sulc"]
-  s.date = %q{2011-03-02}
+  s.date = %q{2011-04-06}
   s.default_executable = %q{sugarcrm}
   s.email = %q{carl.hicks@gmail.com}
   s.executables = ["sugarcrm"]
@@ -78,12 +78,11 @@ Gem::Specification.new do |s|
     "./lib/sugarcrm/module.rb",
     "./lib/sugarcrm/module_methods.rb",
     "./lib/sugarcrm/session.rb",
-    "./sugarcrm.gemspec",
-    "./sugarcrm.tmproj"
+    "./sugarcrm.gemspec"
   ]
   s.homepage = %q{http://github.com/chicks/sugarcrm}
   s.require_paths = ["lib"]
-  s.rubygems_version = %q{1.3.7}
+  s.rubygems_version = %q{1.6.2}
   s.summary = %q{A less clunky way to interact with SugarCRM via REST.}
   s.test_files = [
     "test/connection/test_get_available_modules.rb",
@@ -106,6 +105,7 @@ Gem::Specification.new do |s|
     "test/test_associations.rb",
     "test/test_connection.rb",
     "test/test_connection_pool.rb",
+    "test/test_finders.rb",
     "test/test_module.rb",
     "test/test_response.rb",
     "test/test_session.rb",
@@ -113,7 +113,6 @@ Gem::Specification.new do |s|
   ]
 
   if s.respond_to? :specification_version then
-    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
     s.specification_version = 3
 
     if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then

data/test/test_connection_pool.rb

@@ -18,13 +18,13 @@ class TestConnectionPool < ActiveSupport::TestCase
     end
     
     should "be able to specify its timeout" do
-      assert_equal 5, SugarCRM.session.connection_pool.timeout # test default
+      default_timeout = SugarCRM.session.connection_pool.timeout
       
       config = SugarCRM.session.config
-      sess = SugarCRM::Session.new(config[:base_url], config[:username], config[:password], {:connection_pool => {:wait_timeout => 3}})
+      sess = SugarCRM::Session.new(config[:base_url], config[:username], config[:password], {:connection_pool => {:wait_timeout => default_timeout+1}})
       
       begin
-        assert_equal 3, sess.connection_pool.timeout
+        assert_equal default_timeout+1, sess.connection_pool.timeout
       ensure
         sess.disconnect!
       end