The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

Net::SugarCRM::Tutorial - Net::SugarCRM Overview

DESCRIPTION

The Net::SugarCRM module is a module to provision entries in SugarCRM via REST methods.

All the examples provided here were using the SugarCRM version 6.2.1. See the Sugar Developer Guide for more info http://developers.sugarcrm.com/docs/OS/6.2/-docs-Developer_Guides-Sugar_Developer_Guide_6.2.0-Sugar_Developer_Guide_6.2.1_html.html#9000412

Prerrequisites

Prerequisite: Anyone using this module is supposed to have an understanding (to certain extent) on how SugarCRM works, the different modules that exist in Sugar and how they tie together, and of course a bit of perl :-)

Attributes and modules

The list of attributes for each module (Contacts, Leads, Accounts, ...), can be found in your SugarCRM distribution under modules/$MODULE/vardefs.php, that is to see all the relevant information of the Contacts module, please consult modules/Contacts/vardefs.php. You can use these attributes names during the creation and you receive them back as hash values when you get the module info.

Because of how the internals of SugarCRM work you can only query on the module attributes that are in the SQL tables. That is for the Contacts module only the names that are in the contacts table and contacts_cstm table. As an example, the email1 attribute can be found in the module/Leads/vardefs.php, that means that you can create an entry with that value as follows:

  my $s = Net::SugarCRM->new(url=>$Test::url, restuser=>$Test::login, restpasswd=> $Test::pass);
  my $lead_entry = {
       email1 => 'batman@justiceleague.org',
       salutation => 'Mr',
       first_name => 'Bruce',
       last_name => 'Wayne',
       title => 'Detective',
       account_name => 'Justice League of America',
       department => 'Gotham city dep',
       phone_work => '+1123123123',
       website => 'http://justiceleagueofamerica.org',
  };
  my $leadid = $s->create_lead($lead_entry);

This will work as well (you should get ):

  my $mail = $s->get_lead_attribute($leadid, 'email1')

But because email1 is not in the leads table, this won't work:

  # This does not work
  my $query = 'email1 = "batman@justiceleague.org"';
  my $leads = $s->get_leads($query);

Instead you can use (which is specifically for the email case)

  my $leads = $s->get_leads_from_mail($mail);

For the mail attribute some special methods have been implemented like get_leads_from_mail and similar ones.

About target lists (prospect lists)

To access the normal functionality of this module you need to specify the following attributes:

  • url

    This is the REST url of your SugarCRM installation. For example http://localhost/sugarcrm/service/v4/rest.php. Throughout this document we will use it as $Test::url

  • restuser

    This is the username which has privileges to create, query, delete the entries of the modules. For example admin. In this document we will use it as $Test::login

  • restpasswd

    This is the password of the restuser. In this document we will use it as $Test::pass

If you want to be able to use campaigns module and marketing email distribution as a mail template and be able to resend emails (normally forbidden by the internals of SugarCRM, and specifically by registry in the campaign_logs table) you need to be able to delete some entries of the campaign_logs table. That can only be done (or more precisely, I was only be able to do it with direct access to the tables via SQL. That means that to access this functionality you need to specify also:

  • dsn

    The DBI interface, something like 'DBI:mysql:database=sugarcrm;host=localhost'. In this document you will find it as $Test::testdsn

  • dbuser

    This is the user used for login for the dsn.

  • dbpassword

    This is the password used for login into the database.

Ok, now let's go on to the example

WORKFLOW

We will set up a simple example for a web registration were the workflow is as follows:

  • Demo Registration

    A user registers via web for demo of the product. The relevant lead entry is created in SugarCRM and a demo user is created in LDAP.

  • Email notification

    After the registry we send the user an email with the relevant login information.

  • Use applies to the product

    After a while the user applies for the product, we convert the lead entry into an Account, a Contact and an Opportunity

EXAMPLE

Creation of the sugarcrm object

Example creation of the SugarCRM object

 package Test;
 our $login='admin';
 our $pass='adminpass';
 our $url='http://localhost/sugarcrm/service/v4/rest.php';
 our $testdsn='DBI:mysql:database=sugarcrm;host=localhost';
 our $testdbuser='sugarcrm';
 our $testdbpass='pass';

 package MyPackage;
 my $s = Net::SugarCRM->new(url=>$Test::url, restuser=>$Test::login, restpasswd=> $Test::pass,
        dsn => $Test::testdsn, dbuser => $Test::testdbuser, dbpassword => $Test::testdbpass
 );

Creation of lead entry

Suppose that you got your entry from your web site as a hash, and you want to create a Lead entry. In this example we create an ldap entry and store the initial password also in the CRM. This allows the channel manager to edit the initial email, and be able to insert the password. During the first login the user will be requested to change the password. For this to work you need to add through the Studio interface the attribute initial_password in the Leads module.

 my $lead_entry = {
       email1 => 'batman@justiceleague.org',
       salutation => 'Mr',
       first_name => 'Bruce',
       last_name => 'Wayne',
       title => 'Detective',
       account_name => 'Justice League of America',
       department => 'Gotham city dep',
       phone_work => '+1123123123',
       website => 'http://justiceleagueofamerica.org',
       initial_password_c => _generate_random_pass(),
 };
 # We assume that there is a custom attribute called "initial_password" in the Leads module.
 # You can create it with the Studio interface 
 my $leadid = $s->create_lead($lead_entry);
 # Example creation of ldap entry
 # ... create_entry_in_ldap($lead_entry);

Send of welcome email

Create a campaign called "Demo Campaign", a prospect list called "Demo Users", and marketing email called "Demo Use send password". Be careful this will delete statistics of previous emails sent to this lead and/or email.

 package Test;
 our $testcampaign='Demo Campaign';
 our $testprospectlist='Demo users';
 our $testemailmarketing='Demo User send password';
 
 package MyPackage;
 
 my $attrs = {
        campaign_name => $Test::testcampaign,
        emailmarketing_name => $Test::testemailmarketing, 
        prospectlist_name => $Test::testprospectlist, 
        related_type => 'Leads',
        related_id => $leadid,
        email => 'batman@justiceleague.org',
 };
 $s->send_prospectlist_marketing_email_force($attrs);

Convert the lead to Account, Contact and Opportunity.

 We will get some of the attributes of the lead, and complement them with some
 other info that we probably gather from the web (this is not very efficient
 you should rather get the lead entry and access the hash directly, but
 this is a bit more ilustrative)

 my $leadid = $s->get_unique_lead_id_from_mail('batman@justiceleague.org');
 my $account_attrs = {
       name => $s->get_lead_attribute($leadid, 'account_name'),
       description => 'DC Comics is special...',
       website => $s->get_lead_attribute($leadid, 'website'),
 };
 my $accountid = $s->create_account($account_entry);
 my $contact_entry = {
       email1 => $s->get_lead_attribute($leadid, 'email1'),
       salutation => $s->get_lead_attribute($leadid, 'salutation'),
       first_name => $s->get_lead_attribute($leadid, 'first_name'),
       last_name => $s->get_lead_attribute($leadid, 'last_name'),
       title => $s->get_lead_attribute($leadid, 'title'),
       department => $s->get_lead_attribute($leadid, 'department'),
       phone_work => $s->get_lead_attribute($leadid, 'phone_work'),
       account_id => $accountid,
 };
 my $contactid = $s->create_contact($contact_entry);
 my $opportunity_entry = {
       name => 'My incredible opportunity',
       description => 'This is the former DC Comics is special...',
       amount => '12345',
       sales_stage => 'Prospecting',
       date_closed => '2011-12-31',
       account_id => $accountid,
 };
 my $opportunityid = $s->create_opportunity($opportunity_entry);

And now let's close the lead

 my $new_leadattrs = {
       account_id => $accountid,
       opportunity_id => $opportunity_id,
       contact_id => $contactid,
       status => 'Converted',
       converted => 1,
 };

Add a note

Now let's think that you want to add a note to the opportunity:

 my $note_attrs = {
    name => 'test note',
    description => 'Also a test note descr',
    parent_type => 'Opportunities',
    parent_id => $opportunityid,
    contact_id => $contactid,
 };
 $s->create_note($note_attrs);

Tests

You can find more examples in the test section of the module. Specifically the t/*.t files, customize the t/lib/defaults.pl file with the suitable SugarCRM url and login information and set the environment variables TEST_AUTHOR_SUGAR to run the tests, if you set the variable to DEBUG you will get a lot of debug information.

 export TEST_AUTHOR_SUGAR=1

or

 export TEST_AUTHOR_SUGAR=DEBUG

Please review the tests before you run them, specifically if you are using a production SugarCRM.

EXAMPLE ARCHITECTURE

We describe here an example architecture that we use for our product. The basic restrictions of the design are:

  • Security.

    The website should not have direct access to our customer data (SugarCRM)

  • Philosophy.

    Where possible use OpenSource software, and if possible use perl

The outcome of the design was:

  • Web site

    Web site with wordpress. Any new partner or customer that registers via a web form sents a message to an ActiveMQ queue with a publish/subscription queue.

  • MOM

    The Apache ActiveMQ for queueing up the messages.

  • Provision Module

    Our provisioning module with the logic to create leads, accounts, contacts and opportunities. The technologies used were Any::Event as the event module, Net::STOMP::Client, and <Net::SugarCRM>

  • Customer database

    As the CRM we use SugarCRM

  ----------------------
 |                      |
 |  website (wordpress) |
 |                      |
  ----------------------
            |
            | Publish new requests into queue (lead creation, customer creation)
            |
            v
  ----------------------
 |                      |
 |   Apache ActiveMQ    |
 |                      |
  ----------------------
            ^
            | Subscribe to queue (lead creation, customer creation)
            |
            v
  ----------------------
 |  Net::STOMP::Client  |
 |                      |
 |                      |
 |   Any::Event module  |
 |                      |
 |                      |
 |   Net::SugarCRM      |
  ----------------------
            |
            | Create Lead, Contact, Account, Opportunity (depending on the message received)
            |
            v
  ----------------------
 |                      |
 |   SugarCRM           |
 |                      |
  ----------------------

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Net::SugarCRM

    perldoc Net::SugarCRM::Tutorial

LOGGING

The module uses Net::Log4perl. By default the log level is set to ERROR. An easy way to increase the log level is running this in your script:

 use Log::Log4perl;
 use Net::SugarCRM;
 if(!Log::Log4perl->initialized()) {
    Log::Log4perl->easy_init($Log::Log4perl::DEBUG);
 }

More information

You can also look for information at:

AUTHOR

Nito Martinez, <Nito at Qindel.ES>

http://www.qindel.com

LICENSE AND COPYRIGHT

Copyright 2011 Nito Martinez.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; version 2 dated June, 1991 or at your option any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

A copy of the GNU General Public License is available in the source tree; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.