Web Services in your own language: Part 2 – Ruby

bsoremsugar —  November 16, 2010 — 7 Comments

Editor’s Note: This is part 2 in a series where we highlight using SugarCRM web services with various programming languages. This week’s article comes from Charles Hicks ( known to us Sugas as ‘chicks’ ) our fearless IT Manager, who is also a big Ruby guru. He’s here to talk about connecting to SugarCRM via Ruby and the Ruby Gem he wrote to lessen the pain of doing so…

Interested in talking to SugarCRM with Ruby?  I am, and do… regularly.  The web services API can be a bit daunting for people who are new to SugarCRM, so I designed a Ruby Gem to make simple tasks as straightforward as possible. Using the sugarcrm gem, you can interact with Sugar modules as first class objects!

Ruby Magic

Let’s start with a simple example – you will need ruby 1.8.7 and rubygems installed (if you need help with this, please see the links at the bottom of this post).

When we run this against a SugarCRM instance populated with demo data we see something like:


beans99@example.com
sugar.kid.support@example.co.jp
section.kid.kid@example.edu
dev.sales@example.co.uk
im.kid@example.net

Yes it's really that simple, but what actually happened?

  1. SugarCRM::Base.establish_connection starts a session with the SugarCRM instance.
  2. After session establishment, SugarCRM::Module.register_all is invoked behind the scenes to create an object for each module that is available to the user.
  3. The Accounts module is now accessible as SugarCRM::Account.
  4. Accounts can be searched using find_by_attribute, where attribute is any valid module field (such as website or name). SugarCRM::Account.attributes will show you the available attributes
  5. The find operation will return a single instance of SugarCRM::Account if there is only one result, otherwise it will return an array of SugarCRM::Account objects.
  6. Each SugarCRM::Account object provides access to its attributes as methods (see email.opt_out in the example). You can also access related module records (such as contacts for this account) using the pluralized form of the related module. SugarCRM::Account.associations will show you a complete list of related module methods.
  7. SugarCRM::Account.find_by_name("JAB Funds Ltd.").contacts performs two operations, loading the account, and then loading the contacts.
  8. The contacts method returns an enumerable Array that we loop over with the .each method. We store the current contact in the contact variable.
  9. Since a Contact is related to the Email Address module, we iterate over the email_addresses for each contact.
  10. Finally, we print each email address to the screen if the opt_out flag has not been set.

Direct API

If you find that you need functionality that isn't included in the SugarCRM::Account object, you can access the SugarCRM v2 API methods directly on the connection object like so:

Notes

As a rule, the object name is the singularized form of the Module name, so the Accounts module becomes a "SugarCRM::Account" object. If you aren't sure what something is called you can always inspect the SugarCRM.modules array, or search for a module by name using SugarCRM::Module.find("name"). Most of the module metadata is stored on the resultant object - otherwise you can query field and relationship data a la SugarCRM::Module.find("Accounts").fields (or .link_fields for related modules).

Installation

  1. if you are a Windows user, download the 1.8.7 installer from here. Ruby ships with OS X and most Linux distributions, but you can also download from here.
  2. Install Ruby Gems (if it's not already installed). Instructions are here
  3. Install the sugarcrm gem: gem install sugarcrm
  4. Install the i18n gem: gem install i18n

Connecting

When Things Go Wrong

  • Enable debugging with SugarCRM::Base.establish_connection('http://hostname/sugarcrm', 'user', 'pass', { :debug => true })
  • Submit a bug here

7 responses to Web Services in your own language: Part 2 – Ruby

  1. 
    Matthieu Stone March 30, 2011 at 6:06 am

    Thanks for this – very helpful.

    Any chance of a few more examples? particularly using the related or link fields?

    I’m trying to lookup an Account by email, if it does not exist then create an Account with and associated email.

    thanks.

  2. 

    Does this work with https:// ?

    • 

      Absolutely. 

      • 

         We had our SugarCRM instance redirect all incoming requests to https a previously functioning script now fails with [An existing connection was forcibly closed by the remote host. - SSL_connect (Errno::ECONNRESET)]. Ever seen this?

Trackbacks and Pingbacks:

  1. Ruby Gem for SugarCRM: the Basics | Bridging the geek-suit divide - May 23, 2011

    [...] Ruby gem for SugarCRM has already been briefly presented in a SugarCRM Developer Zone article, but has been drastically improved over the last months. In the following lines, we’ll go [...]

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s