Ruby Gem for SugarCRM: the Basics

The 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 over a few of these improvements and show you how leveraging SugarCRM can be greatly improved.

Setting up

The gem is tested with Ruby 1.8.7 and 1.9.2, so you can pick your favorite version. Installing the gem is as easy as

gem install  sugarcrm

(note: depending on your particular setup, you might need to call ‘sudo gem install’ instead).

If you don’t have a SugarCRM server setup to use for testing, try one of the SugarCRM stack installers.

Since we’ll be executing simple, nearly-independent commands, feel free to follow along in an irb session.

Connecting

The first thing we need to do is

require 'sugarcrm'

after which we can connect to the actual SugarCRM server:

SugarCRM.connect('http://127.0.0.1/sugarcrm','admin','letmein')

(Naturally, this assumes you have your SugarCRM instance running.)

You’ll notice that the URL points to where the SugarCRM server is available on the web server, not the actual index page, nor the API endpoint.

If you’re following along in irb, you’ll see the gem dutifully returns a namespace similar to

SugarCRM::Namespace0

You can safely ignore this for now (we’ll tell you more about it in the advanced article).

Basic CRUD actions

On to our first subject: Create/Read/Update/Delete actions.

Let’s start by seeing which contact was last entered in CRM:

puts SugarCRM::Contact.last.last_name

All SugarCRM modules (i.e. “Contacts”, “Opportunities”, etc.) are namespaced within the ‘SugarCRM’ Ruby module. So ‘SugarCRM::Contact’ gives us access to the ‘Contact’ Ruby class that will wrap all Contacts in CRM. (As a side note, any custom modules you may have created in Studio or loaded with the Module loader will be available in the same fashion.) From that class, we call the ‘last’ finder function (more on those below) which will return the record in SugarCRM with the latest ‘date_entered’ value. Finally, we call the ‘last_name’ attribute on the contact instance to get the person’s last name (which is then printed by Ruby).

Let’s create a new contact:

c = SugarCRM::Contact.create(:first_name => 'John', :last_name => 'Doe')

With respect to creating new class instances and records in CRM, the gem behaves much like ActiveRecord: ‘new’ will create a new class instance without saving it to CRM, whereas ‘create’ will actually save  the class instance on CRM (i.e. create a new record). As we called ‘create’ in this case, our CRM should now have a new record. Let’s check:

puts SugarCRM::Contact.last.last_name # => Doe

Notice we’re calling the same methods as above: we’re still looking for the last created record. However, the output will be different, since we just created a new record. Let’s change John Doe’s last name:

c.last_name = 'Dot'
c.save!

To change the last name, we simply re-assign a value to the attribute. The attribute names always match the SugarCRM field names (which can be looked up in the Studio in the Admin interface), which means that any custom attributes (i.e. that have been added through the Studio tool) will end with ‘_c’. In other words, if we add a “middle name” field to our contact module using the Studio tool, we’ll access that field in the gem by calling ‘my_contact.middle_name_c’.

Once again, the gem behaves like ActiveRecord: ‘save’ will attempt to save the record. If it’s unable to do so (e.g. some required fields are blank), it will simply return false. We’ll call ‘save!’ instead so that if the record can’t be saved, an exception will be raised and the code execution will stop.

Now that we’ve gone through creating, reading, and updating, it’s time to bid farewell to John Doe:

c.delete

Associations

Let’s start by getting a SugarCRM account to work with. (We’ll learn more about finding specific module instances later.)

account = SugarCRM::Account.first

Let’s see how many contacts it has:

puts account.contacts.size

This account just hired a new receptionist. Let’s start by creating a contact in CRM for her (just like we did above):

alice = SugarCRM.create(:last_name => 'Angry', :first_name => 'Alice', :title => 'Receptionist')

Now we can add her to the account’s contacts:

account.contacts << alice
account.save!

&#91;/code&#93;

You can also call 'account.associate!(alice)' which will link the two records and save the relationship in one step. There is a major implementation difference, though: when you call 'account.contacts', it loads all of the account's contacts before creating the new association, which might take a long time. If you just want to make sure the two records are linked and haven't already loaded the associated accounts, it's usually best to call the 'associate' method.

Let's check Alice is now associated with the account, and see how many contacts this account now has:

&#91;code language='ruby'&#93;

puts account.contacts.include? alice
puts account.contacts.size

&#91;/code&#93;

It turns out Alice wasn't a great fit for the company (she didn't really have people skills). Let's remove her from that account:

&#91;code language='ruby'&#93;

account.disassociate!(alice)

&#91;/code&#93;

You could, of course, simply call 'alice.delete' which would delete Alice's record in CRM and all associated relationships, whereas what we did above simply remove the link between the two records, without deleting Alice's record. (In other words, Alice is still in CRM.)

Let's print the full names of all contacts linked to this account, so we can make sure Alice isn't among them:

&#91;code language='ruby'&#93;

account.contacts.each{|c|
puts "#{c.first_name} #{c.last_name}"
}

&#91;/code&#93;

(Let's quickly remove Alice from CRM: 'alice.delete')
<h2>Dynamic finders</h2>
Just like ActiveRecord, the gem provides dynamic finders with attribute names. Here's an easy way to find the "Family Stationary" account:



SugarCRM::Account.find_by_name("Family Stationary")

As you'll see below, this is simply a convenience method that calls a finder with a condition matching the attribute name ('name', in this case) and value ("Family Stationary"). Such methods are available for all attributes defined on your CRM modules.

There is also an "all-in-one" method to ensure a record exists:

SugarCRM::Account.find_or_create_by_name("Family Stationary")

If the record exsits, it will be returned. If no such record exists, it will first be created in CRM, and then returned.

Finders

We've briefly seen how to use the default behavior of the 'first' and 'last' finders. As their name suggests, these finders will return, respectively, the first or last record matching the criteria (if no criteria is given, the default is to sort by date entered). But we can also give conditions to the query: let's search for the first account in Los Angeles:

SugarCRM::Account.first(:conditions => {:billing_address_city => "Los Angeles"})

Notice that conditions are specified within a ':conditions' array. By default, the query will search for records where the attribute is equal to the specified value ("Los Angeles" in this case). But there are other ways to use conditons, as you will see below.

Let's find the first account with a zip code between 50000 and 800000. Notice how, instead of a single value, we've used an array to specify several conditions (including operators). These conditions will be joined with an SQL 'AND' (if you want to use a query with complex boolean algebra, at the time of this writing you'll need to use the direct API method the gem provides, as explained in the "advanced" article).

SugarCRM::Account.first(:conditions => {:billing_address_postalcode => ["> 50000", "<= 80000"&#93;})

&#91;/code&#93;

The last account in California that was created by the administrator (note how conditions are specified on multiple attributes):

&#91;code language='ruby'&#93;

SugarCRM::Account.last(:conditions => {:billing_address_state => "CA", :created_by_name => "Administrator"})

The gem also has (very limited) SQL operator support, although they must be all uppercase to be recognized. Let's print all the accounts with "Inc" in their name:

SugarCRM::Account.all(:conditions => {:name => "LIKE '%Inc%'"}).each{|a| puts a.name }

Notice how this time, instead of calling 'first' or 'last', we called 'all'. The finder syntax is the same for 'all', the difference lies in the return value: 'first' and 'last' will return either an instance matching the criteria or 'nil', whereas 'all' will return an array of matching object instances (or an empty array if there are none).

This shows you how you can iterate across result sets as arrays. The better way to pass each record into a block is this way:

SugarCRM::Account.all(:conditions => {:name => "LIKE '%Inc%'"}){|a| puts a.name }

(Notice the absence of 'each'.) The reason this way is superior is that when 'each' is used, we must must retrieve all matching records before iterating, which can be an issue if there are many. By passing the block directly to the finder as in the second example, records are yielded to the block as each record slice is retrieved.

Finders also accept some SQL arguments: let's print the list of the 10 last accounts (except the last one, due to the 'offset' value) sorted descending by name:

SugarCRM::Account.all(:order_by => "name DESC", :limit => 10, :offset => 1).each{|a| puts a.name }

Of course, you can also add a ':conditions' hash in there. Also to be noted: as of this writing the SugarCRM REST API seems to have a bug where the limit and offset options don't work correctly (the value for limit is always considered to be the smaller of the 2 values). This bug is fixed when using the gem: your query will return the expected results, even if the SugarCRM version you're using has this bug. That's how we roll...

Want to learn more? Check out other articles on this gem: how to create a basic Rails portal for SugarCRM using this gem, and advanced gem use (covering thins like using configuration files for automatic login, extending the gem, etc.).

Gem documentation can be found at https://github.com/chicks/sugarcrm, and questions/problems regarding the gem should be reported there also for quicker resolution.