= SugarCRM

http://github.com/chicks/sugarcrm

REST Bindings for SugarCRM!

== SUMMARY:

A less clunky way to interact with SugarCRM via REST.

== FEATURES/PROBLEMS:

Works with all v2 API calls
Supports Rails 2 and 3
ActiveRecord style finders and objects
Supports creation, saving, and deletion of SugarCRM specific objects
Flexible extension framework
Validations, typecasting, and serialization of boolean, date, and integer fields
Query, update and delete records from collections
Access API methods directly on the SugarCRM.connection object

== SYNOPSIS:

require 'sugarcrm'

Establish a connection

SugarCRM.connect("http://localhost/sugarcrm", 'user', 'password')

Enable debugging on the current connection

SugarCRM.connection.debug = true

Reload the environment (will make the gem classes reflect changes made on SugarCRM server, such as adding fields)

SugarCRM.reload!

Get the logged in user

SugarCRM.current_user

Show a list of available modules

SugarCRM.modules

Retrieve a User by user_name

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") 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

Show the fields required to save

u.required_attributes

Delete an Account

a = SugarCRM::Account.find_by_name("JAB Funds Ltd.") a.delete

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| contact.email_addresses.each do |email| puts "#{email.email_address}" unless email.opt_out end end

Add a Meeting to a Contact

c = SugarCRM::Contact.first c.meetings << SugarCRM::Meeting.new({ :name => "Product Introduction", :date_start => DateTime.now, :duration_hours => 1 }) c.save!

Add a Contact to an Account

a = SugarCRM::Account.find_by_name("JAB Funds Ltd.") c = SugarCRM::Contact.new c.last_name = 'Doe' a.contacts << c a.save # or a.contacts.save

Check if an Account has a specific Contact associated with it

c = SugarCRM::Contact.find_by_last_name("Doe") a = SugarCRM::Account.find_by_name("JAB Funds Ltd.") a.contacts.include?(c)

Remove a Contact from an Account

c = SugarCRM::Contact.find_by_last_name("Doe") a = SugarCRM::Account.find_by_name("JAB Funds Ltd.") 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' })

Retrieve the first 10 Accounts with a zip code between 10000 and 10500

SugarCRM::Account.all({ :conditions => { :billing_address_postalcode => ["> '10000'", "<= '10500'" ] }, :limit => '10', :order_by => 'billing_address_postalcode' })

Retrieve all Accounts with a zip code

SugarCRM::Account.all({ :conditions => { :billing_address_postalcode => "<> NULL" } })

Retrieve all Accounts with 'Fund' in their name

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.

Download a document from SugarCRM

account = SugarCRM::Account.first doc = account.documents.first result = SugarCRM.connection.get_document_revision(doc.document_revision_id) File.open(result['document_revision']['filename'], 'w') do |f| f.write(SugarCRM.connection.b64_decode(result['document_revision']['file'])) }

Create a new document and add it to the account's documents

(continued from above)

doc = SugarCRM::Document.new doc.active_date = Date.today doc.id = doc.save! account.documents << doc account.save!

Create a new revision to add a file to the SugarCRM document instance

(continued from above)

file = File.read(File.join(File.dirname(FILE),"test_excel.xls")) revision_number = 1 SugarCRM.connection.set_document_revision(doc.id, revision_number, { filename: "my_file.xls", file: file })

Look up the fields for a given module

SugarCRM::Module.find("Accounts").fields

Look up the relationships for a given module

SugarCRM::Module.find("Accounts").link_fields

Use the HTTP Connection and SugarCRM API to load the Admin user

SugarCRM.connection.get_entry("Users", 1)

Retrieve all Accounts by user name (direct API method)

SugarCRM.connection.get_entry_list( "Users", "users.user_name = \'sarah\'", { :link_fields => [ { "name" => "accounts", "value" => ["id", "name"] } ]
} )

== USING THE GEM WITH RAILS 3

Note: this gem works with Active Support >= 2.3.10, but is optimized for Rails 3.

Add the sugarcrm gem to your Gemfile (sugarcrm gem version >= 0.9.12)
Run bundle install
Run rails g sugarcrm:config
Edit the configuration file in config/sugarcrm.yml to match your environment

Example apps:

== USING A CONFIGURATION FILE

If you want to use a configuration file instead of always specifying the url, username, and password to connect to SugarCRM, you can add your credentials to one (or more) of

/etc/sugarcrm.yaml
~/.sugarcrm.yaml (i.e. your home directory on Linux and Mac OSX)
a sugarcrm.yaml file at the root of you Windows home directory (execute ENV['USERPROFILE'] in Ruby to see which directory should contain the file)
config/sugarcrm.yaml (will need to be copied each time you upgrade or reinstall the gem)
a YAML file and call SugarCRM.load_config followed by the absolute path to your configuration file

If there are several configuration files, they are loaded sequentially in the order above and will overwrite previous values (if present). This allows you to (e.g.) have a config file in /etc/sugarcrm.yaml with system-wide configuration information (such as the url where SugarCRM is located) and/or defaults. Each developer/user can then have his personal configuration file in ~/.sugarcrm.yaml with his own username and password. A developer could also specify a different location for the SugarCRM instance (e.g. a local testing instance) in his configuration file, which will take precedence over the value in /etc/sugarcrm.yaml.

Your configuration should be in YAML format:

config:
  base_url: http://127.0.0.1/sugarcrm
  username: admin
  password: letmein

An example, accompanied by instructions, can be found in the config/sugarcrm.yaml file. In addition, a working example used for testing can be found in test/config_test.yaml

== USING THE GEM IN A CONSOLE

Type irb in your command prompt
Require the gem with require 'sugarcrm' (Note: Windows users might need to require 'rubygems' before require 'sugarcrm'.)
- if your login credentials are stored in the config/sugarcrm.yaml file, you have been automagically logged in already ;
- if your login credentials are stored in a different config file, just call SugarCRM.load_config followed by the absolute path to your config file. This will log you in automatically ;
- if you don't have a configuration file, you can still call the basic SugarCRM.connect and give it the proper arguments (see documentation above)
You now have full access to the gem's functionality, e.g. puts SugarCRM::Account.first.name
If you make changes on the SugarCRM server (e.g. adding a field to a module), you can call SugarCRM.reload! to rebuild the gem's modules and gain access to the new fields

== EXTENDING THE GEM

If you want to extend the gem's capabilities (e.g. to add methods specific to your environment), you can either

drop your *.rb files in lib/sugarcrm/extensions/ (see the README in that folder)
drop your *.rb files in any other folder and call SugarCRM.extensions_folder = followed by the absolute path to the folder containing your extensions

== WORKING WITH SIMULTANEOUS SESSIONS

This gem allows you to work with several SugarCRM session simultaneously: on each SugarCRM.connect call, a namespace is returned. Make sure you do NOT store this namespace in a reserved name (such as SugarCRM). This namespace can then be used just like you would use the SugarCRM module. For example:

ServerOne = SugarCRM.connect(URL1,...)
ServerOne::User.first
ServerTwo = SugarCRM.connect(URL2,...)
ServerTwo::User.first

If you have only one active session, calls to SugarCRM are delegated to the active session's namespace, like so

ServerOne = SugarCRM.connect(...)
ServerOne::User.first # this call does
SugarCRM::User.first # the exact same thing as this one

To replace your session to connect with different credentials, use

ServerOne.reconnect(...)

Then your session will be reused (SugarCRM modules will be reloaded).

To disconnect an active session:

ServerOne.disconnect!

== REQUIREMENTS:

activesupport >= 2.3.10
i18n
json

== INSTALL:

sudo gem install sugarcrm

Note: Windows users might need to require 'rubygems' before require 'sugarcrm'.

== TEST:

Put your credentials in a file called test/config.yaml (which you will have to create). These must point to a SugarCRM test instance with demo data. See an example file in test/config_test.yaml (leave that file as is).

== Note on Patches/Pull Requests

Fork the project.
Make your feature addition or bug fix.
Add tests for it. This is important so I don't break it in a future version unintentionally.
Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
Send me a pull request. Bonus points for topic branches.

chicks / sugarcrm

readme

Establish a connection

Enable debugging on the current connection

Reload the environment (will make the gem classes reflect changes made on SugarCRM server, such as adding fields)

Get the logged in user

Show a list of available modules

Retrieve a User by user_name

Return a User instance's SugarCRM URL (also works for any other module instance)

Update a User's title

Check if an object is valid (i.e. if it has the required fields to save)

Access the errors collection

Show the fields required to save

Delete an Account

Retrieve all Email Addresses assigned to a particular User.

Retrieve all Email Addresses on an Account

Add a Meeting to a Contact

Add a Contact to an Account

Check if an Account has a specific Contact associated with it

Remove a Contact from an Account

Retrieve the number of accounts in CRM with 'Inc' in their name

Look up the Case with the smallest case number

Retrieve the first 10 Accounts with a zip code between 10000 and 10500

Retrieve all Accounts with a zip code

Retrieve all Accounts with 'Fund' in their name

Use block to iterate over results: print all account names

because records are passed to the block as they get fetched from SugarCRM (whereas `each`

Download a document from SugarCRM

Create a new document and add it to the account's documents

(continued from above)

Create a new revision to add a file to the SugarCRM document instance

(continued from above)

Look up the fields for a given module

Look up the relationships for a given module

Use the HTTP Connection and SugarCRM API to load the Admin user

Retrieve all Accounts by user name (direct API method)

chicks / sugarcrm

readme

Establish a connection

Enable debugging on the current connection

Reload the environment (will make the gem classes reflect changes made on SugarCRM server, such as adding fields)

Get the logged in user

Show a list of available modules

Retrieve a User by user_name

Return a User instance's SugarCRM URL (also works for any other module instance)

Update a User's title

Check if an object is valid (i.e. if it has the required fields to save)

Access the errors collection

Show the fields required to save

Delete an Account

Retrieve all Email Addresses assigned to a particular User.

Retrieve all Email Addresses on an Account

Add a Meeting to a Contact

Add a Contact to an Account

Check if an Account has a specific Contact associated with it

Remove a Contact from an Account

Retrieve the number of accounts in CRM with 'Inc' in their name

Look up the Case with the smallest case number

Retrieve the first 10 Accounts with a zip code between 10000 and 10500

Retrieve all Accounts with a zip code

Retrieve all Accounts with 'Fund' in their name

Use block to iterate over results: print all account names

because records are passed to the block as they get fetched from SugarCRM (whereas each

Download a document from SugarCRM

Create a new document and add it to the account's documents

(continued from above)

Create a new revision to add a file to the SugarCRM document instance

(continued from above)

Look up the fields for a given module

Look up the relationships for a given module

Use the HTTP Connection and SugarCRM API to load the Admin user

Retrieve all Accounts by user name (direct API method)

because records are passed to the block as they get fetched from SugarCRM (whereas `each`