Nito Martinez > Net-SugarCRM > Net::SugarCRM::Tutorial

Download:
Net-SugarCRM-3.23143.tar.gz

Annotate this POD

CPAN RT

Open  0
View/Report Bugs
Source  

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:

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:

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:

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:

The outcome of the design was:

  ----------------------
 |                      |
 |  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.

syntax highlighting: