sugarcrm 0.5.3 → 0.6.0

data/README.rdoc

@@ -6,18 +6,19 @@ REST Bindings for SugarCRM!
 
 == SUMMARY: 
 
-Ruby Gem for interacting with SugarCRM via REST
+Ruby Gem for interacting with SugarCRM via REST.  
 
-== FEATURES/PROBLEMS:
+== Description:
+
+I've implemented all of the basic API calls that SugarCRM supports, and am actively building an abstraction layer
+on top of the basic API methods.  The end result will be to provide ActiveRecord style finders and first class
+objects.  Some of this functionality is included today. 
 
-* The response hash gets converted into a Ruby object, via Hash#to_obj method.
-* Only the following methods are currently implemented:
+== FEATURES/PROBLEMS:
 
-  * get_entry
-  * get_entries
-  * get_entry_list
-  * get_module_fields
-  * get_relationships
+* 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 connection object.
 
 == SYNOPSIS:
 
@@ -25,7 +26,7 @@ Ruby Gem for interacting with SugarCRM via REST
   sugarcrm = SugarCRM::Base.new("http://localhost/sugarcrm", 'user', 'password', {:debug => false})
 
   # Lookup a user by name.  Find any associated accounts
-  sugarcrm.get_entry_list(
+  sugarcrm.connection.get_entry_list(
     "Users",
     "users.user_name = \'#{USER}\'",
     {
@@ -39,8 +40,12 @@ Ruby Gem for interacting with SugarCRM via REST
     } 
   )
 
+	# Retrieve a user by ID, using the SugarCRM::User Proxy object
+	user = SugarCRM::User.find(id)
+
 == REQUIREMENTS:
 
+* activesupport gem
 * json gem
 
 == INSTALL:

data/Rakefile

@@ -6,12 +6,15 @@ begin
   Jeweler::Tasks.new do |gem|
     gem.name = "sugarcrm"
     gem.summary = %Q{Ruby based REST client for SugarCRM}
-    gem.description = %Q{A Ruby based REST client for SugarCRM.}
+    gem.description = %Q{I've implemented all of the basic API calls that SugarCRM supports, and am actively building an abstraction layer
+    on top of the basic API methods.  The end result will be to provide ActiveRecord style finders and first class
+    objects.  Some of this functionality is included today.}
     gem.email = "carl.hicks@gmail.com"
     gem.homepage = "http://github.com/chicks/sugarcrm"
     gem.authors = ["Carl Hicks"]
     gem.add_development_dependency "shoulda", ">= 0"
     gem.add_dependency "json", ">= 0"
+    gem.add_dependency "activesupport", ">= 0"    
     # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
   end
   Jeweler::GemcutterTasks.new

data/VERSION

@@ -1 +1 @@
-0.5.3
+0.6.0

data/lib/sugarcrm.rb

@@ -3,153 +3,141 @@
 module SugarCRM
 
 Dir["#{File.dirname(__FILE__)}/sugarcrm/**/*.rb"].each { |f| load(f) }
-Dir["#{File.dirname(__FILE__)}/stdlib/**/*.rb"].each { |f| load(f) }
 
 require 'pp'
-require 'ostruct'
 require 'uri'
 require 'net/https'
-require 'openssl'
 require 'digest/md5'
 
 require 'rubygems'
+require 'active_support/core_ext'
 require 'json'
-
-class LoginError < RuntimeError
-end
-
-class EmptyResponse < RuntimeError
-end
-
-class UnhandledResponse < RuntimeError
-end
-
-class InvalidSugarCRMUrl < RuntimeError
-end
+require 'json/add/rails'
 
 class Base 
-
-  URL = "/service/v2/rest.php"
-  attr :url, true
-  attr :user, false
-  attr :pass, false
-  attr :ssl, false
-  attr :connection, true
-  attr :session, true
+  # 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.$)/ }
+
+  # This holds our connection
+  cattr_accessor :connection, :instance_writer => false
+  
+  # Contains the name of the module in SugarCRM
+  class_attribute :module_name
+  self.module_name = self.name.split(/::/)[-1]
+  
+  # Contains the fields found on the current module
+  class_attribute :module_fields
+  self.module_fields = {}
+  
+  # Tracks if we have extended our class with attribute methods yet.
+  class_attribute :attribute_methods_generated
+  self.attribute_methods_generated = false
+
+  # Contains a list of attributes
+  attr :attributes, true
   attr :debug, true
-  attr :to_obj, true
 
-  def initialize(url, user, pass, opts={})
+  def self.establish_connection(url, user, pass, opts={})
     options = { 
       :debug  => false,
-      :to_obj => true
     }.merge(opts)
-
     @debug  = options[:debug]
-    @to_obj = options[:to_obj]
-    
-    @url  = URI.parse(url)
-    @user = user
-    @pass = pass
-
-    # Handles http/https in url string
-    @ssl  = false
-    @ssl  = true if @url.scheme == "https"
-
-    # Appends the rest.php path onto the end of the URL if it's not included
-    if @url.path !~ /rest.php$/
-      @url.path += URL
-    end
-      
-    login!
-    raise LoginError, "Invalid Login" unless logged_in?
+    @@connection = SugarCRM::Connection.new(url, user, pass, @debug)
   end
-
-  def connected?
-    return false unless @connection
-    return false unless @connection.started?
-    true
+  
+  # Registers the module fields on the class
+  def self.register_module_fields
+    self.module_fields = connection.get_fields(self.module_name)["module_fields"] if self.module_fields.length == 0
+  end
+  
+  def initialize(attributes={})
+    @attributes = attributes_from_module_fields.merge(attributes)
+    define_attribute_methods
+  end
+  
+  def inspect
+    self
+  end
+  
+  def to_s
+    attrs = []
+    @attributes.each_key do |k|
+       attrs << "#{k}: #{attribute_for_inspect(k)}"
+    end
+    "#<#{self.class} #{attrs.join(", ")}>"
   end
 
-  def logged_in?
-    @session ? true : false
+  # Returns an <tt>#inspect</tt>-like string for the value of the
+  # attribute +attr_name+. String attributes are elided after 50
+  # characters, and Date and Time attributes are returned in the
+  # <tt>:db</tt> format. Other attributes return the value of
+  # <tt>#inspect</tt> without modification.
+  #
+  #   person = Person.create!(:name => "David Heinemeier Hansson " * 3)
+  #
+  #   person.attribute_for_inspect(:name)
+  #   # => '"David Heinemeier Hansson David Heinemeier Hansson D..."'
+  #
+  #   person.attribute_for_inspect(:created_at)
+  #   # => '"2009-01-12 04:48:57"'
+  def attribute_for_inspect(attr_name)
+    value = read_attribute(attr_name)
+
+    if value.is_a?(String) && value.length > 50
+      "#{value[0..50]}...".inspect
+    elsif value.is_a?(Date) || value.is_a?(Time)
+      %("#{value.to_s(:db)}")
+    else
+      value.inspect
+    end
   end
 
   protected
 
-    def connect!
-      @connection = Net::HTTP.new(@url.host, @url.port)
-      if @ssl
-        @connection.use_ssl = true
-        @connection.verify_mode = OpenSSL::SSL::VERIFY_NONE
+  # Generates get/set methods for keys in the attributes hash
+  def define_attribute_methods
+    return if attribute_methods_generated?
+    @attributes.each_pair do |k,v|
+      self.class.module_eval %Q?
+      def #{k}
+        read_attribute :#{k}
       end
-      @connection.start
-    end
-
-    def login!
-      connect! unless connected?
-      json = <<-EOF
-        {
-          \"user_auth\": {
-            \"user_name\": \"#{@user}\"\,
-            \"password\": \"#{OpenSSL::Digest::MD5.new(@pass)}\"\,
-            \"version\": \"2\"\,
-          },
-          \"application\": \"\"
-        }
-      EOF
-      json.gsub!(/^\s{8}/,'')
-      response = get(:login, json)
-
-      if @to_obj
-        @session = response.id
-      else
-        @session = response["id"]
+      def #{k}=(value)
+        write_attribute :#{k},value
       end
+      ?
     end
+    self.class.attribute_methods_generated = true
+  end
 
-    def get(method,json)
-      query =  @url.path.dup
-      query << '?method=' << method.to_s
-      query << '&input_type=JSON'
-      query << '&response_type=JSON'
-      query << '&rest_data=' << json
-
-      if @debug 
-        puts "#{method}: Request"
-        puts query
-        puts "\n"
-      end
-      response = @connection.get(URI.escape(query))
-
-      case response
-        when Net::HTTPOK 
-          raise EmptyResponse unless response.body
-          response_json = JSON.parse response.body
-          return false if response_json["result_count"] == 0
-          if @debug 
-            puts "#{method}: JSON Response:"
-            pp response_json
-            puts "\n"
-          end
-          response_obj = response_json.to_obj 
-      
-          if @to_obj
-            return response_obj
-          else
-            return response_json
-          end
-        when Net::HTTPNotFound
-          raise InvalidSugarCRMUrl, "#{@url} is invalid"
-        else
-          if @debug 
-            puts "#{method}: Raw Response:"
-            puts response.body
-            puts "\n"
-          end
-          raise UnhandledResponse, "Can't handle response #{response}"
-      end
+  # Wrapper around class attribute
+  def attribute_methods_generated?
+    self.class.attribute_methods_generated
+  end
+  
+  def module_fields_registered?
+    self.class.module_fields.length > 0
+  end
+
+  # Returns a hash of the module fields from the 
+  def attributes_from_module_fields
+    self.class.register_module_fields unless module_fields_registered?
+    fields = {}
+    self.class.module_fields.keys.sort.each do |k|
+      fields[k.to_s] = nil
     end
+    fields
+  end
+
+  # Wrapper around attributes hash
+  def read_attribute(key)
+    @attributes[key]
+  end
+  
+  # Wrapper around attributes hash
+  def write_attribute(key, value)
+    @attributes[key] = value
+  end
 
 end
 

data/lib/sugarcrm/api/get_available_modules.rb

@@ -0,0 +1,17 @@
+module SugarCRM; class Connection
+  # Retrieves the list of modules available to the current user logged into the system.  
+  def get_available_modules
+    login! unless logged_in?
+    json = <<-EOF
+      {
+        \"session\": \"#{@session}\"
+      }
+    EOF
+    
+    json.gsub!(/^\s{6}/,'')
+    get(:get_available_modules, json)["modules"]
+  end
+  
+  alias :get_modules :get_available_modules
+  
+end; end

data/lib/sugarcrm/api/get_document_revision.rb

@@ -0,0 +1,14 @@
+module SugarCRM; class Connection
+  # Downloads a particular revision of a document.
+  def get_document_revision(id)
+    login! unless logged_in?
+    json = <<-EOF
+      {
+        \"session\": \"#{@session}\"\,
+        \"id\": #{id}
+      }
+    EOF
+    json.gsub!(/^\s{6}/,'')
+    get(:get_document_revision, json)
+  end
+end; end

data/lib/sugarcrm/{get_entries.rb → api/get_entries.rb}

@@ -1,4 +1,4 @@
-module SugarCRM; class Base
+module SugarCRM; class Connection
 # Retrieve a list of SugarBeans by ID.  This method will not 
 # work with the report module.
 def get_entries(module_name, ids, options={})
@@ -12,7 +12,7 @@ def get_entries(module_name, ids, options={})
     {
       \"session\": \"#{@session}\"\,
       \"module_name\": \"#{module_name}\"\,
-      \"ids\": \"#{ids.to_json}\"\,
+      \"ids\": #{ids.to_json}\,
       \"select_fields\": #{options[:fields].to_json}\,
       \"link_name_to_fields_array\": #{options[:link_fields].to_json}\,
     }

data/lib/sugarcrm/api/get_entries_count.rb

@@ -0,0 +1,20 @@
+module SugarCRM; class Connection
+# Retrieves the specified number of records in a module.
+def get_entries_count(module_name, query, options={})
+  login! unless logged_in?
+  {
+    :deleted => 0, 
+  }.merge! options
+
+  json = <<-EOF
+    {
+      \"session\": \"#{@session}\"\,
+      \"module_name\": \"#{module_name}\"\,
+      \"query\": \"#{query}\"\,
+      \"deleted\": #{options[:deleted]}
+    }
+  EOF
+  json.gsub!(/^\s{6}/,'')
+  get(:get_entries_count, json)
+end
+end; end

data/lib/sugarcrm/{get_entry.rb → api/get_entry.rb}

@@ -1,4 +1,5 @@
-module SugarCRM; class Base
+module SugarCRM; class Connection
+  # Retrieves a single SugarBean based on the ID.
   def get_entry(module_name, id, options={})
     login! unless logged_in?
     { :fields => [], 
@@ -11,15 +12,11 @@ module SugarCRM; class Base
         \"module_name\": \"#{module_name}\"\,
         \"id\": \"#{id}\"\,
         \"select_fields\": #{options[:fields].to_json}\,
+        \"link_name_to_fields_array\": #{options[:link_fields]}\,
       }
     EOF
-    
-    placeholder = <<-EOF
-        \"select_fields\": [\"name\"]
-        \"link_name_to_fields_array\": \"#{options[:link_fields]}\"\,
-    EOF
-    
+        
     json.gsub!(/^\s{6}/,'')
-    get(:get_entry, json)
+    SugarCRM::Response.new(get(:get_entry, json))
   end
 end; end

data/lib/sugarcrm/{get_entry_list.rb → api/get_entry_list.rb}

@@ -1,8 +1,8 @@
-module SugarCRM; class Base
+module SugarCRM; class Connection
 # Retrieve a list of SugarBeans.  This is the primary method for getting 
 # a list of SugarBeans using the REST API.
 def get_entry_list(module_name, query, options={})
-  login! unless logged_in?
+  login! unless logged_in?  
   {
     :order_by => '', 
     :offset => '', 

data/lib/sugarcrm/{get_module_fields.rb → api/get_module_fields.rb}

@@ -1,7 +1,8 @@
-module SugarCRM; class Base
-  
+module SugarCRM; class Connection
+
+# Retrieves the vardef information on fields of the specified bean.  
 def get_module_fields(module_name)
-  login! unless logged_in?
+  login! unless logged_in?  
   json = <<-"EOF"
     {
       \"session\": \"#{@session}\"\,
@@ -12,4 +13,6 @@ def get_module_fields(module_name)
   get(:get_module_fields, json)
 end
 
+alias :get_fields :get_module_fields
+
 end; end