sugarcrm 0.7.9 → 0.8.0

data/README.rdoc

@@ -12,14 +12,15 @@ RubyGem for interacting with SugarCRM via REST.
 
 A less clunky way to interact with SugarCRM via REST.
 
-I've built an abstraction layer on top of the SugarCRM REST API, instead of +get_entry("Users", "1")+ you can 
-call +SugarCRM::User.find(1)+.  There is also support for collections à la +SugarCRM::User.find(1).accounts+.  
+I've built an abstraction layer on top of the SugarCRM REST API, instead of get_entry("Users", "1") you can 
+call SugarCRM::User.find(1).  There is also support for collections à la SugarCRM::User.find(1).email_addresses.  
 ActiveRecord style finders are in place, with limited support for conditions and joins 
-e.g. +SugarCRM::Contacts.find_by_title("VP of Sales")+ will work, but +SugarCRM::Contacts.find_by_title("VP of Sales", {:conditions => {:deleted => 0}})+ will not.  
+e.g. SugarCRM::Contacts.find_by_title("VP of Sales") will work, but SugarCRM::Contacts.find_by_title("VP of Sales", {:conditions => {:deleted => 0}}) will not.  
 
 == FEATURES/PROBLEMS:
 
 * Supports all v2 API calls
+* Supports saving of Module specific objects.
 * Auto-generation of Module specific objects.  When a connection is established, get_available_modules is called and the resultant modules are turned into SugarCRM::Module classes.  
 * If you just want to use the vanilla API, you can access the methods directly on the SugarCRM.connection object.
 
@@ -28,7 +29,10 @@ e.g. +SugarCRM::Contacts.find_by_title("VP of Sales")+ will work, but +SugarCRM:
   require 'sugarcrm'
   
   # Establish a connection
-  SugarCRM::Base.establish_connection("http://localhost/sugarcrm", 'user', 'password', {:debug => false})
+  SugarCRM.connect("http://localhost/sugarcrm", 'user', 'password')
+
+  # Enable debugging on the current connection
+  SugarCRM.connection.debug = true
 
   # Get the logged in user
   SugarCRM.current_user
@@ -38,9 +42,24 @@ e.g. +SugarCRM::Contacts.find_by_title("VP of Sales")+ will work, but +SugarCRM:
 
   # Retrieve a User by user_name
   SugarCRM::User.find_by_user_name("admin")
+  
+  # Update a User's title
+  u = SugarCRM::User.find_by_first_name_and_last_name("Will", "Westin")
+  u.title = "Sales Manager Central"
+  u.save
+  
+  # Check if an object is valid (i.e. if it has the required fields to save)
+  u.valid?
+  
+  # Access the errors collection
+  u.errors
+  
+  # Delete an Account
+  a = SugarCRM::Account.find_by_name("JAB Funds Ltd.")
+  a.delete
 
-  # Retrieve all Contacts assigned to a particular user.
-  SugarCRM::User.find_by_user_name('sarah').contacts
+  # Retrieve all Email Addresses assigned to a particular user.
+  SugarCRM::User.find_by_user_name('sarah').email_addresses
   
   # Retrieve all email addresses on an Account
   SugarCRM::Account.find_by_name("JAB Funds Ltd.").contacts.each do |contact|

data/VERSION

@@ -1 +1 @@
-0.7.9
+0.8.0

data/lib/sugarcrm.rb

@@ -1,4 +1,5 @@
 require 'pp'
+require 'set'
 require 'rubygems'
 require 'active_support/core_ext'
 

data/lib/sugarcrm/association_methods.rb

@@ -1,8 +1,10 @@
 module SugarCRM; module AssociationMethods
   
-  # Returns an array of the module link fields
-  def associations_from_module_link_fields
-    self.class._module.link_fields.keys
+  module ClassMethods
+    # Returns an array of the module link fields
+    def associations_from_module_link_fields
+      self._module.link_fields.keys
+    end
   end
   
   # Generates the association proxy methods for related modules
@@ -30,8 +32,7 @@ module SugarCRM; module AssociationMethods
   #     "type"=>"link"},
   #
   def query_association(association)
-    klass = self.class._module.link_fields[association.to_s]["module"]
-    objects = SugarCRM.connection.get_relationships(
+    collection = SugarCRM.connection.get_relationships(
       self.class._module.name,
       self.id,
       association.to_s

data/lib/sugarcrm/attribute_methods.rb

@@ -3,13 +3,95 @@ module SugarCRM; module AttributeMethods
   module ClassMethods
     # Returns a hash of the module fields from the module
     def attributes_from_module_fields
-      fields = {}
+      fields = {}.with_indifferent_access
       self._module.fields.keys.sort.each do |k|
         fields[k.to_s] = nil
       end
       fields
     end
   end
+  
+  # Determines if attributes have been changed
+  def changed?
+    @modified_attributes.length > 0
+  end
+  
+  # Is this a new record?
+  def new?
+    @id.blank?
+  end
+
+  # Converts the attributes hash into format recognizable by Sugar
+  # { :last_name => "Smith"} 
+  # becomes
+  # { :last_name => {:name => "last_name", :value => "Smith"}}
+  def serialize_attributes
+    attr_hash = {}
+    @attributes.each_pair do |name,value|
+      attr_hash[name] = serialize_attribute(name,value)
+    end
+    attr_hash[:id] = serialize_id unless new?
+    attr_hash
+  end
+
+  # Converts the modified_attributes hash into format recognizable by Sugar
+  # { :last_name => {:old => "Smit", :new => "Smith"}} 
+  # becomes
+  # { :last_name => {:name => "last_name", :value => "Smith"}}  
+  def serialize_modified_attributes
+    attr_hash = {}
+    @modified_attributes.each_pair do |name,hash|
+      attr_hash[name] = serialize_attribute(name,hash[:new])
+    end
+    attr_hash[:id] = serialize_id unless new?
+    attr_hash
+  end
+
+  # Checks to see if we have all the neccessary attributes
+  def valid?
+    valid = true
+    self.class._module.required_fields.each do |attribute|
+      case attr_type_for(attribute)
+      when "bool"
+        case @attributes[attribute]
+        when TrueClass:
+          next
+        when FalseClass:
+          next
+        else
+          @errors.add "#{attribute} must be true or false"
+          valid = false
+        end
+      else 
+        if @attributes[attribute].blank?
+          @errors.add "#{attribute} cannot be blank"
+          valid = false
+        end
+      end
+    end
+    valid
+  end
+  
+  # List the required attributes for save
+  def required_attributes
+    self.class._module.required_fields
+  end
+
+  # Serializes the id
+  def serialize_id
+    {:name => "id", :value => @id.to_s}
+  end
+
+  # Un-typecasts the attribute - false becomes 0
+  def serialize_attribute(name,value)
+    attr_value = value
+    case attr_type_for(name)
+    when "bool"
+      attr_value = 0
+      attr_value = 1 if value
+    end
+    {:name => name, :value => attr_value}
+  end
 
   # Generates get/set methods for keys in the attributes hash
   def define_attribute_methods
@@ -52,6 +134,26 @@ module SugarCRM; module AttributeMethods
   end
 
   protected
+  
+  # Returns the attribute type for a given attribute
+  def attr_type_for(attribute)
+    field = self.class._module.fields[attribute]
+    return false unless field
+    field["type"]
+  end
+  
+  # Attempts to typecast each attribute based on the module field type
+  def typecast_attributes
+    @attributes.each_pair do |name,value|
+      attr_type = attr_type_for(name)
+      next unless attr_type
+      case attr_type
+      when "bool"
+        @attributes[name] = (value == "1")
+      end
+    end
+    @attributes
+  end
 
   # Wrapper around attributes hash
   def read_attribute(key)
@@ -60,6 +162,7 @@ module SugarCRM; module AttributeMethods
   
   # Wrapper around attributes hash
   def write_attribute(key, value)
+    @modified_attributes[key] = { :old => @attributes[key].to_s, :new => value }
     @attributes[key] = value
   end
   

data/lib/sugarcrm/base.rb

@@ -4,7 +4,7 @@ require 'sugarcrm/association_methods'
 module SugarCRM; class Base 
 
   # Unset all of the instance methods we don't need.
-  instance_methods.each { |m| undef_method m unless m =~ /(^__|^send$|^object_id$|^define_method$|^class$|^instance_of.$)/ }
+  instance_methods.each { |m| undef_method m unless m =~ /(^__|^send$|^object_id$|^define_method$|^class$|^methods$|^instance_of.$|^respond_to.$)/ }
 
   # This holds our connection
   cattr_accessor :connection, :instance_writer => false
@@ -21,9 +21,11 @@ module SugarCRM; class Base
   
   # Contains a list of attributes
   attr :attributes, true
+  attr :modified_attributes, true
   attr :associations, true
   attr :id, true
   attr :debug, true
+  attr :errors, true
 
   class << self # Class methods
     def establish_connection(url, user, pass, opts={})
@@ -74,7 +76,7 @@ module SugarCRM; class Base
 
       case ids.size
         when 0
-          raise RecordNotFound, "Couldn't find #{name} without an ID"
+          raise RecordNotFound, "Couldn't find #{self._module.name} without an ID"
         when 1
           result = find_one(ids.first, options)
           expects_array ? [ result ] : result
@@ -124,6 +126,8 @@ module SugarCRM; class Base
     end
     
     def query_from_options(options)
+      # If we dont have conditions, just return an empty query
+      return "" unless options[:conditions]
       conditions = []
       options[:conditions].each_pair do |column, value| 
         conditions << "#{self._module.table_name}.#{column} = \'#{value}\'"
@@ -282,9 +286,13 @@ module SugarCRM; class Base
   def initialize(id=nil, attributes={})
     @id = id
     @attributes = self.class.attributes_from_module_fields.merge(attributes)
-    @associations = associations_from_module_link_fields
+    @modified_attributes = {}
+    @associations = self.class.associations_from_module_link_fields
+    @errors = Set.new
     define_attribute_methods
     define_association_methods
+    typecast_attributes
+    self
   end
 
   def inspect
@@ -293,16 +301,38 @@ module SugarCRM; class Base
   
   def to_s
     attrs = []
-    @attributes.each_key do |k|
-       attrs << "#{k}: #{attribute_for_inspect(k)}"
+    @attributes.keys.sort.each do |k|
+      attrs << "#{k}: #{attribute_for_inspect(k)}"
     end
     "#<#{self.class} #{attrs.join(", ")}>"
   end
 
+  # Saves the current object, checks that required fields are present.
+  # returns true or false
   def save
-    response = SugarCRM.connection.set_entry(self._module.name, @attributes)
+    return false unless changed?
+    return false unless valid?
+    # If we get a Hash back, return true.  Otherwise return false.
+    (SugarCRM.connection.set_entry(self.class._module.name, serialize_modified_attributes).class == Hash)
+  end
+  
+  # Saves the current object, checks that required fields are present.
+  # raises an exception if a save fails
+  def save!
+    raise InvalidRecord, errors.to_a.join(", ") unless valid?
+    # If we get a Hash back, return true.  Otherwise return false.
+    (SugarCRM.connection.set_entry(self.class._module.name, serialize_modified_attributes).class == Hash)   
   end
   
+  def delete
+    return false if @id.blank?
+    params          = {}
+    params[:id]     = serialize_id
+    params[:deleted]= {:name => "deleted", :value => "1"}
+    (SugarCRM.connection.set_entry(self.class._module.name, params).class == Hash)       
+  end
+    
+  
   # Wrapper around class attribute
   def attribute_methods_generated?
     self.class.attribute_methods_generated
@@ -316,6 +346,7 @@ module SugarCRM; class Base
     include AttributeMethods
     extend  AttributeMethods::ClassMethods
     include AssociationMethods
+    extend  AssociationMethods::ClassMethods
   end
 
 end; end 

data/lib/sugarcrm/connection.rb

@@ -87,6 +87,10 @@ module SugarCRM; class Connection
     options[:debug] = debug
   end
   
+  def debug?
+    options[:debug]
+  end
+  
   private
   
   def handle_response

data/lib/sugarcrm/connection/api/get_entries.rb

@@ -3,7 +3,8 @@ module SugarCRM; class Connection
 # work with the report module.
 def get_entries(module_name, ids, opts={})
   login! unless logged_in?
-  options = { :fields => [], 
+  options = { 
+    :fields => [], 
     :link_fields => [], 
   }.merge! opts
 

data/lib/sugarcrm/connection/api/get_entries_count.rb

@@ -2,7 +2,9 @@ module SugarCRM; class Connection
 # Retrieves the specified number of records in a module.
 def get_entries_count(module_name, query, opts={})
   login! unless logged_in?
-  options = {:deleted => 0}.merge! opts
+  options = {
+    :deleted => 0
+  }.merge! opts
 
   json = <<-EOF
     {

data/lib/sugarcrm/connection/api/get_entry.rb

@@ -2,7 +2,8 @@ module SugarCRM; class Connection
   # Retrieves a single SugarBean based on the ID.
   def get_entry(module_name, id, opts={})
     login! unless logged_in?
-    options = { :fields => [], 
+    options = { 
+      :fields => [], 
       :link_fields => [], 
     }.merge! opts
     

data/lib/sugarcrm/connection/api/get_entry_list.rb

@@ -8,8 +8,8 @@ def get_entry_list(module_name, query, opts={})
     :offset => '', 
     :fields => [], 
     :link_fields => [], 
-    :max_results => '', 
-    :deleted => ''
+    :limit => '', 
+    :deleted => 0
   }.merge! opts
 
   json = <<-EOF
@@ -21,7 +21,7 @@ def get_entry_list(module_name, query, opts={})
       \"offset\": \"#{options[:offset]}\"\,
       \"select_fields\": #{resolve_fields(module_name, options[:fields])}\,
       \"link_name_to_fields_array\": #{options[:link_fields].to_json}\,
-      \"max_results\": \"#{options[:max_results]}\"\,
+      \"max_results\": \"#{options[:limit]}\"\,
       \"deleted\": #{options[:deleted]}
     }
   EOF

data/lib/sugarcrm/connection/api/search_by_module.rb

@@ -2,12 +2,13 @@ module SugarCRM; class Connection
   # Returns the ID, module name and fields for specified modules. 
   # Supported modules are Accounts, Bugs, Calls, Cases, Contacts, 
   # Leads, Opportunities, Projects, Project Tasks, and Quotes.
-  def search_by_module(search_string, modules, options={})
+  def search_by_module(search_string, modules, ops={})
     login! unless logged_in?
     
-    { :offset => nil, 
-      :max_results => nil, 
-    }.merge! options
+    options = { 
+      :offset => nil, 
+      :limit => nil, 
+    }.merge! opts
     
     json = <<-EOF
       {
@@ -15,7 +16,7 @@ module SugarCRM; class Connection
         \"search_string\": \"#{search_string}\"\,
         \"modules\": \"#{modules}\"\,
         \"offset\": #{options[:offset]}\,
-        \"max_results\": #{options[:max_results]}
+        \"max_results\": #{options[:limit]}
       }
     EOF
     json.gsub!(/^\s{6}/,'')

data/lib/sugarcrm/connection/helper.rb

@@ -3,7 +3,12 @@ module SugarCRM; class Connection
     # FIXME: This is to work around a bug in SugarCRM 6.0
     # where no fields are returned if no fields are specified
     if fields.length == 0
-      fields = Module.find(module_name).fields.keys
+      mod = Module.find(module_name)
+      if mod
+        fields = mod.fields.keys
+      else  
+        fields = "id"
+      end
     end
     return fields.to_json
   end

data/lib/sugarcrm/exceptions.rb

@@ -22,4 +22,7 @@ module SugarCRM
   
   class RecordNotFound < RuntimeError
   end
+  
+  class InvalidRecord < RuntimeError
+  end
 end

data/lib/sugarcrm/module.rb

@@ -33,6 +33,16 @@ module SugarCRM
       @fields_registered
     end
     
+    def required_fields
+      required_fields = []
+      ignore_fields = ["id", "date_entered", "date_modified"]
+      self.fields.each_value do |field|
+        next if ignore_fields.include? field["name"]
+        required_fields << field["name"] if field["required"] == 1
+      end 
+      required_fields
+    end
+    
     def link_fields
       self.fields unless link_fields?
       handle_empty_array

data/lib/sugarcrm/module_methods.rb

@@ -7,6 +7,12 @@ module SugarCRM
   def self.connection=(connection)
     @@connection = connection
   end
+  def self.connect(url, user, pass, options={})
+    SugarCRM::Base.establish_connection(url, user, pass, options)
+  end
+  class << self
+    alias :connect! :connect
+  end
   
   @@modules = []
   def self.modules

data/lib/sugarcrm/response.rb

@@ -8,7 +8,12 @@ module SugarCRM; class Response
       r = new(json)
       begin
         return r.to_obj
-      rescue
+      rescue => e
+        if SugarCRM.connection.debug?
+          puts "Failed to process JSON:"
+          pp json
+          puts e
+        end
         return json
       end
     end
@@ -23,18 +28,17 @@ module SugarCRM; class Response
   # Tries to instantiate and return an object with the values
   # populated from the response
   def to_obj
+    # If this is not a "entry_list" response, just return
+    return @response unless @response["entry_list"]
+    
     objects = []
     @response["entry_list"].each do |object|
       attributes = []
       _module    = resolve_module(object)
       id         = object["id"]
-      begin
-        attributes = flatten_name_value_list(object)
-      rescue ArgumentError => e
-      end
+      attributes = flatten_name_value_list(object)
       if SugarCRM.const_get(_module)
         if attributes.length == 0
-          pp object
           raise AttributeParsingError, "response contains objects without attributes!"
         end
         objects << SugarCRM.const_get(_module).new(id, attributes) 
@@ -53,7 +57,7 @@ module SugarCRM; class Response
   def to_json
     @response.to_json
   end
-  
+    
   def resolve_module(list)
     list["module_name"].classify
   end

data/test/connection/test_get_entry.rb

@@ -16,5 +16,8 @@ class TestGetEntry < Test::Unit::TestCase
     should "return an object when #get_entry" do 
       assert_instance_of SugarCRM::User, @response
     end
+    should "typecast boolean fields properly" do
+      assert !(@response.deleted)
+    end
   end
 end

data/test/helper.rb

@@ -8,7 +8,7 @@ require 'sugarcrm'
 
 class Test::Unit::TestCase
   # Replace these with your test instance
-  URL   = "http://valet/sugarcrm6"
+  URL   = "http://valet/sugarcrm"
   USER  = "admin"
   PASS  = 'letmein' 
 

data/test/test_module.rb

@@ -10,5 +10,9 @@ class TestModule < Test::Unit::TestCase
     should "respond to #fields" do
       assert_respond_to SugarCRM.modules[0], :fields
     end
+    
+    should "return required fields when #required_fields" do
+      assert SugarCRM::User._module.required_fields.include? "user_name"
+    end
   end
 end

data/test/test_sugarcrm.rb

@@ -3,6 +3,11 @@ require 'helper'
 class TestSugarCRM < Test::Unit::TestCase
   context "A SugarCRM::Base instance" do
     
+    should "establish a connection when SugarCRM#connect!" do
+      SugarCRM.connect!(URL, USER, PASS)
+      assert SugarCRM.connection.connected?
+    end
+    
     should "establish a connection when Base#establish_connection" do
       SugarCRM::Base.establish_connection(URL, USER, PASS)
       assert SugarCRM.connection.connected?
@@ -12,6 +17,10 @@ class TestSugarCRM < Test::Unit::TestCase
       assert_equal "Users", SugarCRM::User._module.name
     end
     
+    should "responsd to self#methods" do
+      assert_instance_of Array, SugarCRM::User.new.methods
+    end
+    
     should "respond to self.connection" do
       assert_respond_to SugarCRM::User, :connection
       assert_instance_of SugarCRM::Connection, SugarCRM::User.connection
@@ -26,7 +35,7 @@ class TestSugarCRM < Test::Unit::TestCase
     end
   
     should "respond to self.attributes_from_modules_fields" do
-      assert_instance_of Hash, SugarCRM::User.attributes_from_module_fields
+      assert_instance_of ActiveSupport::HashWithIndifferentAccess, SugarCRM::User.attributes_from_module_fields
     end
   
     should "return an instance of itself when #new" do
@@ -38,10 +47,31 @@ class TestSugarCRM < Test::Unit::TestCase
       assert SugarCRM::User.attribute_methods_generated
     end
 
-    should "respond to attributes derived from #_module.fields" do
+    should "not save a record that is missing required attributes" do
       u = SugarCRM::User.new
       u.last_name = "Test"
-      assert_equal "Test", u.last_name
+      assert !u.save
+      assert_raise SugarCRM::InvalidRecord do
+        u.save!
+      end
+    end
+
+    should "create, modify, and delete a record" do
+      #SugarCRM.connection.debug = true
+      u = SugarCRM::User.new
+      u.email1 = "abc@abc.com"
+      u.first_name = "Test"
+      u.last_name = "User"
+      u.system_generated_password = false
+      u.user_name = "test_user"
+      u.status = "Active"
+      assert_equal "Test", u.modified_attributes[:first_name][:new]
+      assert u.save!
+      m = SugarCRM::User.find_by_first_name_and_last_name("Test", "User")
+      m.title = "Test User"
+      assert m.save!
+      assert m.delete
+      #SugarCRM.connection.debug = false
     end
     
     should "return an an instance of itself when sent #find(id)" do

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: sugarcrm
 version: !ruby/object:Gem::Version 
-  hash: 17
+  hash: 63
   prerelease: false
   segments: 
   - 0
-  - 7
-  - 9
-  version: 0.7.9
+  - 8
+  - 0
+  version: 0.8.0
 platform: ruby
 authors: 
 - Carl Hicks
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-11-14 00:00:00 -08:00
+date: 2010-12-04 00:00:00 -08:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency