NAME

Net::SugarCRM - A simple module to access SugarCRM via Rest services

VERSION

Version $Revision: 23143 $

DESCRIPTION

This is a simple module to provision entries in SugarCRM via REST methods.

This is for example to be able to provision contacts, leads, accounts via web services and be able to integrate Sugar with other applications.

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_ht ml.html#9000412

Most of the attributes values that you can use, you need to get them from the description of the mysql tables leads, accounts, contacts, ...

Examples

    # Sometimes the encryption parameter seems necessary
    # my $s = Net::SugarCRM->new(url=>$Test::url, restuser=>$Test::login, restpasswd=> md5_hex($Test::pass));
    # or you have to encode the password as md5_hex
    # my $s = Net::SugarCRM->new(url=>$Test::url, restuser=>$Test::login, restpasswd=> $Test::pass);
    # 
    
    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);
   ...
   my $account_entry = {
       email1 => 'dc@dc.neverland',
       name => 'DC Comics',
       description => 'DC Comics is special...',
       website => 'http://dccomics.neverland',
       annual_revenue => '12345',
       phone_office => '1123123124',
   };
   my $accountid = $s->create_account($account_entry);
   my $account_entries_from_mail = $s->get_accounts_from_mail('dc@dc.neverland');
   # this method croaks if you've got more the email more than once
   my $accountid = $s->get_unique_account_id_from_mail($mail);
   my $phone_office = $s->get_account_attribute($accountid, 'phone_office');
   ...
   my $mail = 'superman@justiceleague.org';
   my $contact_entry = {
       email1 => $mail,
       salutation => 'Mr',
       first_name => 'Clark',
       last_name => 'Kent123',
       title => 'SuperHero',
       department => 'Metropolis dep',
       phone_work => '+1123123124',
   };
   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);
   my $query = 'opportunities.name = "My incredible opportunity"';
   my $opid2 = $s->get_unique_opportunity_id($query);
   ...
   # Now try to send a campaign email bypassing previous sent emails
   # For this you need to have access to the SugarCRM database to
   # manipulate the campaign_log
   $s->dsn('DBI:mysql:database=sugarcrm;host=localhost');
   $s->dbuser($Test::testdbuser);
   $s->dbpassword($Test::testdbpass);
   # You need to have created the campaign, target list (prospect_list), and email_marketing
   # entry and mail template
   my $attrs = {
        campaign_name => 'My Demo Campaign',
        emailmarketing_name => 'Demo users send greetings', 
        prospectlist_name => 'Demo users', 
        related_type => 'Leads',
        related_id => $leadid,
        email => 'batman@justiceleague.org',
   };

ATTRIBUTES

url

The default url to access, if not defined http://localhost/sugarcrm/service/v4/rest.php

restuser

the username for login in the rest method

restpasswd

the password for login in the rest method

Sometimes the encryption parameter seems to be necessary to use plain password (See https://rt.cpan.org/Ticket/Display.html?id=93696), or you can manually encode the password as md5_hex, that is.

 $self->restpasswd(md5_hex('mypass'))

globalua

The default useragent

application

The application name to be used for the rest method in sugar

email_attr

The SugarCRM attribute name for email

required_attr

Hash reference to the required attrs for a lead, contact, account

dsn

Datasource Name: the configuration string for the database. For example:

DBI:mysql:database=qvd;host=localhost

dbuser

the user to connect to the database

dbpassword

the password of user to connect to the database

dbh

the database handler

sessionid

Returns the sessionid after the login. If it is not defined, it tries to do a login.

max_results

The maximum number of results a get_entry_list returns. By default it is 1000

METHODS

it uses the object attributes url, restuser and restpasswd for the login. It returns the sessionid. And it also stores the sessionid in the object. Normally you don't need to call this method it is implicitly called

On some SugarCRM PRO it seems that it is needed to set $self->encryption('PLAIN')

The code would be something like

 my $sugar = Net::SugarCRM->new(url=>$Test::url, restuser=>$Test::login, restpasswd=> $Test::pass);
 $sugar->encryption('PLAIN');
 $sugar->login

On error the method croaks

encryption

encryption if set it will add the "encryption" parameter to the login service REST message.

The valid values currently are "PLAIN", although this is not enforced. If it is undef, the parameter is not passed in the login method.

logout

Input: session id

On error the method croaks. Normally you don't need to invoke this method it is implicitly called.

Modules

get_available_modules

Input:

 * session id

Output:

 * ref to an array of modules. On error the method croaks

get_module_fields

Input:

 * Module names

Output: * ref to an array of modules. On error the method croaks

Generic module methods

create_module_entry

Input:

 * Module name: Contacts, Accounts, Notes, Leads
 * A hash reference of attributes for the entry. Valid values depend on the module name, ...

Output:

 * The created id for the module entry. On error the method croaks

get_module_entries

Returns the entries for a given module, searching for an attribute

Input: * query string. This must be one of the valid attributes in the module or module_cstm table, for example for Leads these would be the leads or leads_cstm table. Examples (Note email1 does not work as a valid attribute although it works for create_lead): "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'"

Output:

 * A reference to a an array of module entries,
   [] if none found, and 
   confess on error
 
 my $s = Net::SugarCRM->new(url=>$Test::url, restuser=>$Test::login, restpasswd=> $Test::pass);
 my $lead_entries_from_mail = $s->get_module_entries('Leads', 'website = "http://justiceleagueofamerica.org"');
 for my $l (@$lead_entries_from_mail) {
    print Dumper($l);
 }

get_module_ids

Returns an array of module ids, searching for query see get_module_entries for more info.

Input: * query * module

Output:

 * A reference to an array of module ids, and confess on error

get_unique_module_id

Returns the module id, searching for query $query If none is found undef is returned, and if more than one is found an error is issued.

This method should only be used if you can garantee that you have only one module entry for the given query

Input: * query (see get_module_entries for more info)

Output:

 * entry id found, 0 if none is found, and confess on error or if more than
   one leadid is found.

get_module_entry

Returns the module entry, given a module name and a module id

Input: * module name * id

Output:

 * A module entry,
   undef if none found, and 
   confess on error

get_module_attribute

Returns the value of the attribute for a given module and module id, If the attribute or module id is not found undef is returned. On error the method confess

Input: * module name * module id * attribute name

Output:

 * attribute value or undef (if the leadid is not found, the attribute does not exists)
 
 my $s = Net::SugarCRM->new(url=>$Test::url, restuser=>$Test::login, restpasswd=> $Test::pass);
 try {
      my $lead_entry = $s->get_unique_lead_id_from_mail('batman@justiceleague.org');
      if (!defined($lead_entry)) {
         print "Not found\n";
      } else {
         print $s->get_module_attribute('Leads', $lead_entry, 'last_name');
      }
 } catch {
    print "Error or more than one entry was found: $@";
 }

get_module_entries_from_mail

Returns the module ids, searching for mail

Input: * module name * email address

Output:

 * A reference to a an array of module entries,
   [] if none found, and 
   confess on error, or the module does not searching by mail address

 my $s = Net::SugarCRM->new(url=>$Test::url, restuser=>$Test::login, restpasswd=> $Test::pass);
 my $lead_entries_from_mail = $s->get_module_entries_from_mail('Leads', 'batman@justiceleague.org');
 for my $l (@$lead_entries_from_mail) {
    print Dumper($l);
 }

get_module_ids_from_mail

Returns an array of module id, searching for mail

Input: * email address

Output:

 * A reference to an array of module id, and confess on error

 my $s = Net::SugarCRM->new(url=>$Test::url, restuser=>$Test::login, restpasswd=> $Test::pass);
 my $lead_entries_from_mail = $s->get_module_ids_from_mail('Leads', 'batman@justiceleague.org');
 for my $l (@$lead_entries_from_mail) {
    print Dumper($l);
 }

get_unique_module_id_from_mail

Returns the module id, searching for mail If none is found undef is returned, and if more than one is found an error is issued.

This method should only be used if you can garantee that you have only one module entry with the same email address

Input: * email address

Output:

 * module id found, 0 if none is found, and confess on error or if more than
   one leadid is found.
 
 my $s = Net::SugarCRM->new(url=>$Test::url, restuser=>$Test::login, restpasswd=> $Test::pass);
 try {
      my $lead_entry = $s->get_unique_module_id_from_mail('Leads', 'batman@justiceleague.org');
      if (!defined($lead_entry)) {
         print "Not found\n";
      } else {
         print "$lead_entry\n";
      }
 } catch {
    print "Error or more than one entry was found: $@";
 }

delete_module_entry_by_id

Deletes the module entry indicated by id

Input: * module name * entry id

Output:

 * 1 if the module id was modified, 0 if the id was not found and confess on error

 my $s = Net::SugarCRM->new(url=>$Test::url, restuser=>$Test::login, restpasswd=> $Test::pass);
 try {
      my $lead_entry = $s->get_unique_lead_id_from_mail('batman@justiceleague.org');
      if (!defined($lead_entry)) {
         print "Not found\n";
      } else {
         $s->delete_module_entry_by_id('Leads', $lead_entry);
         print "$lead_entry\n";
      }
 } catch {
    print "Error or more than one entry was found: $@";
 }

get_module_link_ids

Returns related ids for a given module, searching for an id

Input:

 * module name
 * link_field_name
 * module id
 * query (which might be empty)
 * related_fields (which might be empty and if not it should be a reference to an array of fields). By default this is ["id"]

Output:

 * A reference to an array of related ids

Example: Get all the opportunity ids of account id $accountid

my $ids = $s->get_module_link_ids("Accounts", "opportunities", $accountid); print Dumper($ids);

update_module_entry

Updates the module entry attributes

Input: * module name * module id * A hash reference of attribute pairs. Example { website => 'http://newsite.org'}

Output:

 * 1 if the id was modified, 0 if the id was not found and confess on error

 my $s = Net::SugarCRM->new(url=>$Test::url, restuser=>$Test::login, restpasswd=> $Test::pass);
 try {
      my $lead_entry = $s->get_unique_lead_id_from_mail('batman@justiceleague.org');
      if (!defined($lead_entry)) {
         print "Not found\n";
      } else {
         $s->update_module_entry('Leads', $lead_entry, { website => 'http://newsite.org' });
         print "$lead_entry\n";
      }
 } catch {
    print "Error or more than one entry was found: $@";
 }

Lead

Leads methods

create_lead

Input:

 * A hash reference of attributes for the Lead. Valid values are first_name, last_name, email1, account_name, title, department, phone_work, website, ...

Output:

 * The created id for the lead

On error the method confess

Example:

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

get_leads

Returns the lead entry, searching for an attribute

Input: * query string. This must be one of the valid attributes in the leads or leads_cstm table. Examples (Note email1 does not work as a valid attribute although it works for create_lead): "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'"

Output:

 * A reference to a an array of lead entries,
   [] if none found, and 
   confess on error
 
 my $s = Net::SugarCRM->new(url=>$Test::url, restuser=>$Test::login, restpasswd=> $Test::pass);
 my $lead_entries_from_mail = $s->get_leads('website = "http://justiceleagueofamerica.org"');
 for my $l (@$lead_entries_from_mail) {
    print Dumper($l);
 }

get_lead_ids

Returns an array of lead id, searching for query see get_leads for more info.

Input: * query

Output:

 * A reference to an array of lead id, and confess on error

get_unique_lead_id

Returns the lead id, searching for query $query If none is found undef is returned, and if more than one is found an error is issued.

This method should only be used if you can garantee that you have only one lead with the same email address

Input: * query (see get_leads for more info)

Output:

 * leadid found, 0 if none is found, and confess on error or if more than
   one leadid is found.

get_lead

Returns the lead entry, given an leadid

Input: * leadid

Output:

 * A lead entry,
   undef if none found, and 
   confess on error

get_lead_attribute

Returns the value of the attribute for a given lead id, If the attribute or lead id is not found undef is returned.

Input: * leadid * attribute name

Output:

 * attribute value or undef (if the leadid is not found, the attribute does not exists)
 
 my $s = Net::SugarCRM->new(url=>$Test::url, restuser=>$Test::login, restpasswd=> $Test::pass);
 try {
      my $lead_entry = $s->get_unique_lead_id_from_mail('batman@justiceleague.org');
      if (!defined($lead_entry)) {
         print "Not found\n";
      } else {
         print $s->get_lead_attribute($lead_entry, 'last_name');
      }
 } catch {
    print "Error or more than one entry was found: $@";
 }

get_leads_from_mail

Returns the lead id, searching for mail

Input: * email address

Output:

 * A reference to a an array of lead entries,
   [] if none found, and 
   confess on error
 
 my $s = Net::SugarCRM->new(url=>$Test::url, restuser=>$Test::login, restpasswd=> $Test::pass);
 my $lead_entries_from_mail = $s->get_leads_from_mail('batman@justiceleague.org');
 for my $l (@$lead_entries_from_mail) {
    print Dumper($l);
 }

get_lead_ids_from_mail

Returns an array of lead id, searching for mail

Input: * email address

Output:

 * A reference to an array of lead id, and confess on error

 my $s = Net::SugarCRM->new(url=>$Test::url, restuser=>$Test::login, restpasswd=> $Test::pass);
 my $lead_entries_from_mail = $s->get_lead_ids_from_mail('batman@justiceleague.org');
 for my $l (@$lead_entries_from_mail) {
    print Dumper($l);
 }

get_unique_lead_id_from_mail

Returns the lead id, searching for mail If none is found undef is returned, and if more than one is found an error is issued.

This method should only be used if you can garantee that you have only one lead with the same email address

Input: * email address

Output:

 * leadid found, undef if none is found, and confess on error or if more than
   one leadid is found.
 
 my $s = Net::SugarCRM->new(url=>$Test::url, restuser=>$Test::login, restpasswd=> $Test::pass);
 try {
      my $lead_entry = $s->get_unique_lead_id_from_mail('batman@justiceleague.org');
      if (!defined($lead_entry)) {
         print "Not found\n";
      } else {
         print "$lead_entry\n";
      }
 } catch {
    print "Error or more than one entry was found: $@";
 }

delete_lead_by_id

Deletes the leadid indicated by $id

Input: * leadid

Output:

 * 1 if the leadid was modified, 0 if no leadid was found and confess on error

 my $s = Net::SugarCRM->new(url=>$Test::url, restuser=>$Test::login, restpasswd=> $Test::pass);
 try {
      my $lead_entry = $s->get_unique_lead_id_from_mail('batman@justiceleague.org');
      if (!defined($lead_entry)) {
         print "Not found\n";
      } else {
         $s->delete_lead_by_id($lead_entry);
         print "$lead_entry\n";
      }
 } catch {
    print "Error or more than one entry was found: $@";
 }

update_lead

Updates the lead attributes

Input: * leadid * A hash reference of attribute pairs. Example { website => 'http://newsite.org'}

Output:

 * 1 if the leadid was modified, 0 if no leadid was found and confess on error

 my $s = Net::SugarCRM->new(url=>$Test::url, restuser=>$Test::login, restpasswd=> $Test::pass);
 try {
      my $lead_entry = $s->get_unique_lead_id_from_mail('batman@justiceleague.org');
      if (!defined($lead_entry)) {
         print "Not found\n";
      } else {
         $s->update_lead($lead_entry, { website => 'http://newsite.org' });
         print "$lead_entry\n";
      }
 } catch {
    print "Error or more than one entry was found: $@";
 }

Contacts

Contacts methods

create_contact

Input:

 * A hash reference of attributes for the Contact. Valid values are first_name, last_name, email1, ...

To reference it to an account include the attribute "account_id" pointing it to an account.

Output:

 * The created id for the contact

On error the method confess

get_contacts

Returns the contact entry, searching for an attribute

Input: * query string. This must be one of the valid attributes in the contacts or contacts_cstm table. Examples (Note email1 does not work as a valid attribute although it works for create_contact): "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'"

Output:

 * A reference to a an array of contact entries,
   [] if none found, and 
   confess on error
 
 my $s = Net::SugarCRM->new(url=>$Test::url, restuser=>$Test::login, restpasswd=> $Test::pass);
 my $contact_entries_from_mail = $s->get_contacts('website = "http://justiceleagueofamerica.org"');
 for my $l (@$contact_entries_from_mail) {
    print Dumper($l);
 }

get_contact_ids

Returns an array of contact id, searching for query see get_contacts for more info.

Input: * query

Output:

 * A reference to an array of contact id, and confess on error

get_unique_contact_id

Returns the contact id, searching for query $query If none is found undef is returned, and if more than one is found an error is issued.

This method should only be used if you can garantee that you have only one contact with the same email address

Input: * query (see get_contacts for more info)

Output:

 * contactid found, 0 if none is found, and confess on error or if more than
   one contactid is found.

get_contact

Returns the contact entry, given an contactid

Input: * contactid

Output:

 * A contact entry,
   undef if none found, and 
   confess on error

get_contact_attribute

Returns the value of the attribute for a given contact id, If the attribute or contact id is not found undef is returned.

Input: * contactid * attribute name

Output:

 * attribute value or undef (if the contactid is not found, the attribute does not exists)
 
 my $s = Net::SugarCRM->new(url=>$Test::url, restuser=>$Test::login, restpasswd=> $Test::pass);
 try {
      my $contact_entry = $s->get_unique_contact_id_from_mail('batman@justiceleague.org');
      if (!defined($contact_entry)) {
         print "Not found\n";
      } else {
         print $s->get_contact_attribute($contact_entry, 'last_name');
      }
 } catch {
    print "Error or more than one entry was found: $@";
 }

get_contacts_from_mail

Returns the contact id, searching for mail

Input: * email address

Output:

 * A reference to a an array of contact entries,
   [] if none found, and 
   confess on error
 
 my $s = Net::SugarCRM->new(url=>$Test::url, restuser=>$Test::login, restpasswd=> $Test::pass);
 my $contact_entries_from_mail = $s->get_contacts_from_mail('batman@justiceleague.org');
 for my $l (@$contact_entries_from_mail) {
    print Dumper($l);
 }

get_contact_ids_from_mail

Returns an array of contact id, searching for mail

Input: * email address

Output:

 * A reference to an array of contact id, and confess on error

 my $s = Net::SugarCRM->new(url=>$Test::url, restuser=>$Test::login, restpasswd=> $Test::pass);
 my $contact_entries_from_mail = $s->get_contact_ids_from_mail('batman@justiceleague.org');
 for my $l (@$contact_entries_from_mail) {
    print Dumper($l);
 }

get_unique_contact_id_from_mail

Returns the contact id, searching for mail If none is found undef is returned, and if more than one is found an error is issued.

This method should only be used if you can garantee that you have only one contact with the same email address

Input: * email address

Output:

 * contactid found, 0 if none is found, and confess on error or if more than
   one contactid is found.
 
 my $s = Net::SugarCRM->new(url=>$Test::url, restuser=>$Test::login, restpasswd=> $Test::pass);
 try {
      my $contact_entry = $s->get_unique_contact_id_from_mail('batman@justiceleague.org');
      if (!defined($contact_entry)) {
         print "Not found\n";
      } else {
         print "$contact_entry\n";
      }
 } catch {
    print "Error or more than one entry was found: $@";
 }

get_contact_account_ids

Find all accounts associated with the specified contact

Input:

  * contactid

Output:

  * A reference to an array of account ids

delete_contact_by_id

Deletes the contactid indicated by $id

Input: * contactid

Output:

 * 1 if the contactid was modified, 0 if no contactid was found and confess on error

 my $s = Net::SugarCRM->new(url=>$Test::url, restuser=>$Test::login, restpasswd=> $Test::pass);
 try {
      my $contact_entry = $s->get_unique_contact_id_from_mail('batman@justiceleague.org');
      if (!defined($contact_entry)) {
         print "Not found\n";
      } else {
         $s->delete_contact_by_id($contact_entry);
         print "$contact_entry\n";
      }
 } catch {
    print "Error or more than one entry was found: $@";
 }

update_contact

Updates the contact attributes

Input: * contactid * A hash reference of attribute pairs. Example { website => 'http://newsite.org'}

Output:

 * 1 if the contactid was modified, 0 if no contactid was found and confess on error

 my $s = Net::SugarCRM->new(url=>$Test::url, restuser=>$Test::login, restpasswd=> $Test::pass);
 try {
      my $contact_entry = $s->get_unique_contact_id_from_mail('batman@justiceleague.org');
      if (!defined($contact_entry)) {
         print "Not found\n";
      } else {
         $s->update_contact($contact_entry, { website => 'http://newsite.org' });
         print "$contact_entry\n";
      }
 } catch {
    print "Error or more than one entry was found: $@";
 }

Accounts

Accounts methods

create_account

Input:

 * A hash reference of attributes for the Account. Valid values are first_name, last_name, email1, ...

To reference it to an account include the attribute "account_id" pointing it to an account.

Output:

 * The created id for the account

On error the method confess

get_accounts

Returns the account entry, searching for an attribute

Input: * query string. This must be one of the valid attributes in the accounts or accounts_cstm table. Examples (Note email1 does not work as a valid attribute although it works for create_account): "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'"

Output:

 * A reference to a an array of account entries,
   [] if none found, and 
   confess on error
 
 my $s = Net::SugarCRM->new(url=>$Test::url, restuser=>$Test::login, restpasswd=> $Test::pass);
 my $account_entries_from_mail = $s->get_accounts('website = "http://justiceleagueofamerica.org"');
 for my $l (@$account_entries_from_mail) {
    print Dumper($l);
 }

get_account_ids

Returns an array of account id, searching for query see get_accounts for more info.

Input: * query

Output:

 * A reference to an array of account id, and confess on error

get_unique_account_id

Returns the account id, searching for query $query If none is found undef is returned, and if more than one is found an error is issued.

This method should only be used if you can garantee that you have only one account with the same email address

Input: * query (see get_accounts for more info)

Output:

 * accountid found, 0 if none is found, and confess on error or if more than
   one accountid is found.

get_account

Returns the account entry, given an accountid

Input: * accountid

Output:

 * A account entry,
   undef if none found, and 
   confess on error

get_account_attribute

Returns the value of the attribute for a given account id, If the attribute or account id is not found undef is returned.

Input: * accountid * attribute name

Output:

 * attribute value or undef (if the accountid is not found, the attribute does not exists)
 
 my $s = Net::SugarCRM->new(url=>$Test::url, restuser=>$Test::login, restpasswd=> $Test::pass);
 try {
      my $account_entry = $s->get_unique_account_id_from_mail('batman@justiceleague.org');
      if (!defined($account_entry)) {
         print "Not found\n";
      } else {
         print $s->get_account_attribute($account_entry, 'last_name');
      }
 } catch {
    print "Error or more than one entry was found: $@";
 }

get_accounts_from_mail

Returns the account id, searching for mail

Input: * email address

Output:

 * A reference to a an array of account entries,
   [] if none found, and 
   confess on error
 
 my $s = Net::SugarCRM->new(url=>$Test::url, restuser=>$Test::login, restpasswd=> $Test::pass);
 my $account_entries_from_mail = $s->get_accounts_from_mail('batman@justiceleague.org');
 for my $l (@$account_entries_from_mail) {
    print Dumper($l);
 }

get_account_ids_from_mail

Returns an array of account id, searching for mail

Input: * email address

Output:

 * A reference to an array of account id, and confess on error

 my $s = Net::SugarCRM->new(url=>$Test::url, restuser=>$Test::login, restpasswd=> $Test::pass);
 my $account_entries_from_mail = $s->get_account_ids_from_mail('batman@justiceleague.org');
 for my $l (@$account_entries_from_mail) {
    print Dumper($l);
 }

get_unique_account_id_from_mail

Returns the account id, searching for mail If none is found undef is returned, and if more than one is found an error is issued.

This method should only be used if you can garantee that you have only one account with the same email address

Input: * email address

Output:

 * accountid found, 0 if none is found, and confess on error or if more than
   one accountid is found.
 
 my $s = Net::SugarCRM->new(url=>$Test::url, restuser=>$Test::login, restpasswd=> $Test::pass);
 try {
      my $account_entry = $s->get_unique_account_id_from_mail('batman@justiceleague.org');
      if (!defined($account_entry)) {
         print "Not found\n";
      } else {
         print "$account_entry\n";
      }
 } catch {
    print "Error or more than one entry was found: $@";
 }

get_account_contact_ids

Find all contacts associated with the specified account

Input:

  * accountid

Output:

  * A reference to an array of contact ids

delete_account_by_id

Deletes the accountid indicated by $id

Input: * accountid

Output:

 * 1 if the accountid was modified, 0 if no accountid was found and confess on error

 my $s = Net::SugarCRM->new(url=>$Test::url, restuser=>$Test::login, restpasswd=> $Test::pass);
 try {
      my $account_entry = $s->get_unique_account_id_from_mail('batman@justiceleague.org');
      if (!defined($account_entry)) {
         print "Not found\n";
      } else {
         $s->delete_account_by_id($account_entry);
         print "$account_entry\n";
      }
 } catch {
    print "Error or more than one entry was found: $@";
 }

update_account

Updates the account attributes

Input: * accountid * A hash reference of attribute pairs. Example { website => 'http://newsite.org'}

Output:

 * 1 if the accountid was modified, 0 if no accountid was found and confess on error

 my $s = Net::SugarCRM->new(url=>$Test::url, restuser=>$Test::login, restpasswd=> $Test::pass);
 try {
      my $account_entry = $s->get_unique_account_id_from_mail('batman@justiceleague.org');
      if (!defined($account_entry)) {
         print "Not found\n";
      } else {
         $s->update_account($account_entry, { website => 'http://newsite.org' });
         print "$account_entry\n";
      }
 } catch {
    print "Error or more than one entry was found: $@";
 }

Currency

Currency methods

create_currency

Input:

 * A hash reference of attributes for the Currency. Valid values are name, symbol, iso4217, conversion_rate

Output:

 * The created id for the currency

get_currencies

Returns the currency entry, searching for an attribute

Input: * query string. This must be one of the valid attributes in the currencies or currencies_cstm table. Output:

 * A reference to a an array of currency entries,
   [] if none found, and 
   confess on error

get_currency_ids

Returns an array of currency id, searching for query see get_currencies for more info.

Input: * query

Output:

 * A reference to an array of currency id, and confess on error

get_unique_currency_id

Returns the currency id, searching for query $query If none is found undef is returned, and if more than one is found an error is issued.

This method should only be used if you can garantee that you have only one currency with the same email address

Input: * query (see get_currencies for more info)

Output:

 * currencyid found, 0 if none is found, and confess on error or if more than
   one currencyid is found.

get_currency

Returns the currency entry, given an currencyid

Input: * currencyid

Output:

 * A currency entry,
   undef if none found, and 
   confess on error

get_currency_attribute

Returns the value of the attribute for a given currency id, If the attribute or currency id is not found undef is returned.

Input: * currencyid * attribute name

Output:

 * attribute value or undef (if the currencyid is not found, the attribute does not exists)

delete_currency_by_id

Deletes the currencyid indicated by $id

Input: * currencyid

Output:

 * 1 if the currencyid was modified, 0 if no currencyid was found and confess on error

update_currency

Updates the currency attributes

Input: * currencyid * A hash reference of attribute pairs. Example { website => 'http://newsite.org'}

Output:

 * 1 if the currencyid was modified, 0 if no currencyid was found and confess on error

Opportunity

Opportunity methods

create_opportunity

Input:

 * A hash reference of attributes for the Opportunity. Valid values are first_name, last_name, email1, ...

To reference it to an opportunity include the attribute "opportunity_id" pointing it to an opportunity.

Output:

 * The created id for the opportunity

On error the method confess

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 $opportunityid2 = $s->create_opportunity($opportunity_entry);

get_opportunities

Returns the opportunity entry, searching for an attribute

Input: * query string. This must be one of the valid attributes in the opportunities or opportunities_cstm table. Examples (Note email1 does not work as a valid attribute although it works for create_opportunity): "salutation = 'Mr'" "first_name = 'Bruce'" "last_name = 'Wayne'" "title => 'Detective'" "opportunity_name = 'Justice League of America'" "department = 'Gotham city dep'" "phone_work = '+1123123123'" "website = 'http://justiceleagueofamerica.org'"

Output:

 * A reference to a an array of opportunity entries,
   [] if none found, and 
   confess on error
 
 my $s = Net::SugarCRM->new(url=>$Test::url, restuser=>$Test::login, restpasswd=> $Test::pass);
 my $opportunity_entries_from_mail = $s->get_opportunities('website = "http://justiceleagueofamerica.org"');
 for my $l (@$opportunity_entries_from_mail) {
    print Dumper($l);
 }

get_opportunity_ids

Returns an array of opportunity id, searching for query see get_opportunities for more info.

Input: * query

Output:

 * A reference to an array of opportunity id, and confess on error

get_unique_opportunity_id

Returns the opportunity id, searching for query $query If none is found undef is returned, and if more than one is found an error is issued.

This method should only be used if you can garantee that you have only one opportunity with the same email address

Input: * query (see get_opportunities for more info)

Output:

 * opportunityid found, 0 if none is found, and confess on error or if more than
   one opportunityid is found.

get_opportunity

Returns the opportunity entry, given an opportunityid

Input: * opportunityid

Output:

 * A opportunity entry,
   undef if none found, and 
   confess on error

get_opportunity_attribute

Returns the value of the attribute for a given opportunity id, If the attribute or opportunity id is not found undef is returned.

Input: * opportunityid * attribute name

Output:

 * attribute value or undef (if the opportunityid is not found, the attribute does not exists)
 
 my $s = Net::SugarCRM->new(url=>$Test::url, restuser=>$Test::login, restpasswd=> $Test::pass);
 try {
      my $opportunity_entry = $s->get_unique_opportunity_id_from_mail('batman@justiceleague.org');
      if (!defined($opportunity_entry)) {
         print "Not found\n";
      } else {
         print $s->get_opportunity_attribute($opportunity_entry, 'last_name');
      }
 } catch {
    print "Error or more than one entry was found: $@";
 }

get_opportunities_from_mail

Returns the opportunity id, searching for mail

Input: * email address

Output:

 * A reference to a an array of opportunity entries,
   [] if none found, and 
   confess on error
 
 my $s = Net::SugarCRM->new(url=>$Test::url, restuser=>$Test::login, restpasswd=> $Test::pass);
 my $opportunity_entries_from_mail = $s->get_opportunities_from_mail('batman@justiceleague.org');
 for my $l (@$opportunity_entries_from_mail) {
    print Dumper($l);
 }

get_opportunity_ids_from_mail

Returns an array of opportunity id, searching for mail

Input: * email address

Output:

 * A reference to an array of opportunity id, and confess on error

 my $s = Net::SugarCRM->new(url=>$Test::url, restuser=>$Test::login, restpasswd=> $Test::pass);
 my $opportunity_entries_from_mail = $s->get_opportunity_ids_from_mail('batman@justiceleague.org');
 for my $l (@$opportunity_entries_from_mail) {
    print Dumper($l);
 }

get_unique_opportunity_id_from_mail

Returns the opportunity id, searching for mail If none is found undef is returned, and if more than one is found an error is issued.

This method should only be used if you can garantee that you have only one opportunity with the same email address

Input: * email address

Output:

 * opportunityid found, 0 if none is found, and confess on error or if more than
   one opportunityid is found.
 
 my $s = Net::SugarCRM->new(url=>$Test::url, restuser=>$Test::login, restpasswd=> $Test::pass);
 try {
      my $opportunity_entry = $s->get_unique_opportunity_id_from_mail('batman@justiceleague.org');
      if (!defined($opportunity_entry)) {
         print "Not found\n";
      } else {
         print "$opportunity_entry\n";
      }
 } catch {
    print "Error or more than one entry was found: $@";
 }

delete_opportunity_by_id

Deletes the opportunityid indicated by $id

Input: * opportunityid

Output:

 * 1 if the opportunityid was modified, 0 if no opportunityid was found and confess on error

 my $s = Net::SugarCRM->new(url=>$Test::url, restuser=>$Test::login, restpasswd=> $Test::pass);
 try {
      my $opportunity_entry = $s->get_unique_opportunity_id_from_mail('batman@justiceleague.org');
      if (!defined($opportunity_entry)) {
         print "Not found\n";
      } else {
         $s->delete_opportunity_by_id($opportunity_entry);
         print "$opportunity_entry\n";
      }
 } catch {
    print "Error or more than one entry was found: $@";
 }

update_opportunity

Updates the opportunity attributes

Input: * opportunityid * A hash reference of attribute pairs. Example { website => 'http://newsite.org'}

Output:

 * 1 if the opportunityid was modified, 0 if no opportunityid was found and confess on error

 my $s = Net::SugarCRM->new(url=>$Test::url, restuser=>$Test::login, restpasswd=> $Test::pass);
 try {
      my $opportunity_entry = $s->get_unique_opportunity_id_from_mail('batman@justiceleague.org');
      if (!defined($opportunity_entry)) {
         print "Not found\n";
      } else {
         $s->update_opportunity($opportunity_entry, { website => 'http://newsite.org' });
         print "$opportunity_entry\n";
      }
 } catch {
    print "Error or more than one entry was found: $@";
 }

Mail

mail methods

get_mail_entry

Returns the EmailAddress entry, searching for mail address

Input: * email address

Output:

 * the EmailAddress entry, undef if none found, and confess on error

get_mail_entry_id

Returns the emailaddress id, searching for mail Adds the lead identified by id to the specified to the outgoing email

Input: * email address

Output:

 * the contact id, undef if none found, and confess on error

Note

Notes methods

create_note

contact_id, description, name =subject

parent_type -> Accounts, Opportunities parent_id -> account_id or opportunity_id

get_note

Returns the note entry, given an noteid

Input: * noteid

Output:

 * A Note entry,
   undef if none found, and 
   confess on error

get_note_attribute

Returns the value of the attribute for a given note id, If the attribute or note id is not found undef is returned.

Input: * noteid * attribute name

Output:

 * attribute value or undef (if the noteid is not found, the attribute does not exists)

delete_note_by_id

Deletes the note indicated by $id

Input: * noteid

Output:

 * 1 if the opportunityid was modified, 0 if no opportunityid was found and confess on error

Campaigns

get_campaignid_by_name

Returns a campaign id searching for the campaign name,

Input:

 * Campaign name

Output:

 * if duplicate names exists
an error is thrown (confess), if not found undef is returned and if found the campaign id
is returned

get_campaign

Returns the campaign entry, given a campaign id

Input: * campaignid

Output:

 * A campaign entry,
   undef if none found, and 
   confess on error

get_campaign_attribute

Returns the value of the attribute for a given campaing id, If the attribute or campaing id is not found undef is returned.

Input: * campaignid * attribute name

Output:

 * attribute value or undef (if the leadid is not found, the attribute does not exists)

Prospectlists

get_prospectlistid_by_name

Returns a prospectlist id searching for the prospectlist name,

Input:

 * Prospectlist name

Output:

 * if duplicate names exists
an error is thrown (confess), if not found undef is returned and if found the prospectlist id
is returned

get_prospectlist

Returns the prospectlist entry, given a prospectlist id

Input: * prospectlistid

Output:

 * A prospectlist entry,
   undef if none found, and 
   confess on error

get_prospectlist_attribute

Returns the value of the attribute for a given campaing id, If the attribute or campaing id is not found undef is returned.

Input: * prospectlistid * attribute name

Output:

 * attribute value or undef (if the leadid is not found, the attribute does not exists)

EmailMarketing

get_emailmarketingid_by_name

Returns a emailmarketing id searching for the emailmarketing name,

Input:

 * Emailmarketing name

Output:

 * if duplicate names exists
an error is thrown (confess), if not found undef is returned and if found the emailmarketing id
is returned

get_emailmarketing

Returns the emailmarketing entry, given a emailmarketing id

Input: * emailmarketingid

Output:

 * A emailmarketing entry,
   undef if none found, and 
   confess on error

get_emailmarketing_attribute

Returns the value of the attribute for a given campaing id, If the attribute or campaing id is not found undef is returned.

Input: * emailmarketingid * attribute name

Output:

 * attribute value or undef (if the leadid is not found, the attribute does not exists)

Prospect Lists

add_module_id_to_prospect_list

Adds the lead identified by id to the specified target list

Input: * Module (currently only Contacts and Leads are supported) * Lead id or contact id * Target list id

Output:

 * Returns 1 on success and undef if the entry was not created
   confess on error

delete_module_id_from_prospect_list

Gets the leads and contacts ids from the specified target list

Input: * Target list id

Output:

 * A reference to a hash with the entries ,confess on error

add_lead_id_to_prospect_list

Adds the lead identified by id to the specified target list

Input: * Lead id * Target list id

Output:

 * 1 if the lead was added undef if not
   confess on error

add_contact_id_to_prospect_list

Adds the contact identified by id to the specified target list

Input: * Contact id * Target list id

Output:

 * 1 if the lead was added undef if not
   confess on error

delete_lead_id_from_prospect_list

Note: This method does not seem to work

Deletes the lead identified by id from the specified target list

Input: * Lead id * Target list id

Output:

 * 1 if the lead was added undef if not
   confess on error

delete_contact_id_from_prospect_list

Note: This method does not seem to work

Deletes the contact identified by id from the specified target list

Input: * Contact id * Target list id

Output:

 * 1 if the lead was added undef if not
   confess on error

Campaign emails

These methods are to send emails out.

send_prospectlist_marketing_email_force

Note: Be careful you might resend emails that were already sent, this function overrides that.

This method gets as input: * Hash array: * campaign_name: campaign name, * emailmarketing_name: marketing name (this is the name of the name that holds the email template) * prospectlist_name: Prospect list, where the contact or lead is going to be added * related_name: Can be one of two values Leads or Contacts * related_id: The leadid or contactid * email: The email of the contact

Output:

 * undef if the email was not put in the outbound queue, confess in case of error.

this method is a facility method to add contact to a prospect_list, delete all the relevant entries in the campaign log, and put the email in the outbound queue (emailman)

add_to_emailman

Adds the module entry identified by some attributes to the specified to the outgoing email.

This method puts in the outbound queue the mail specified by marketing_id, related_id and list_id (to resend a previous sent email you need to specifically delete the entries in the campaign log, see delete_ids_from_campaignlog

Input: * A hash with the following elements at least * campaign_id e6c3a792-9d03-c063-3601-4e2ad8991061 * marketing_id e6c3a792-9d03-c063-3601-4e2ad8991061 * list_id 55308e7d-1d97-9a8f-dc30-4e2ad69623af * related_id, new id created, * related_type, Leads or Contacts

Output:

 * the hash created,confess on error

Side effect the way we generate the ids, there should be at least a millisecond between each insert...

    my $emailman_attrs = {
        campaign_id => $campaignid,
        marketing_id => $emailmarketingid,
        list_id => $prospectlistid,
        related_id => $leadid, 
        related_type => 'Leads',
        user_id => 'f2347eb8-b5ed-b324-a316-4e26c9558337',
        modified_user_id => 'f2347eb8-b5ed-b324-a316-4e26c9558337',
    };
    ok($s->add_to_emailman($emailman_attrs), "Added mails to emailman");

get_ids_from_campaignlog

Returns the id, searching for campaign_id, target_id, target_type, list_id, marketing_id

Input: * hash with * campaign_id * target_id * target_type * list_id * marketing_id * email

Output:

 * an array ref with the campaign logs id,  if none found an empty hash array, and confess on error

delete_ids_from_campaignlog

Returns the id, searching for campaign_id, target_id, target_type, list_id, marketing_id Adds the lead identified by id to the specified to the outgoing email

For this method to work you need to get the database configuration set up see sttributes dsn, dbuser and dbpassword

Input: * reference to an array with campaign log ids to be deleted

Output:

 * None, confess on error

    my $attrs = {
        campaign_id => $campaignid,
        target_id => $contactid,
        target_type => 'Contacts',
        list_id => $prospectlistid,
        marketing_id => $emailmarketingid,
    };
    my $ids = $s->get_ids_from_campaignlog($attrs);
    $s->delete_ids_from_campaignlog($ids);

DESTROY

if the object is dereferenced and the sessionid is defined a logout is issued

update

Save the values of a Net::SugarCRM::Entry

TODO

convert lead

AUTHOR

Nito Martinez, <Nito at Qindel.ES>

BUGS

Please report any bugs or feature requests to bug-sugarcrm-client-rest at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Net-SugarCRM. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

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

    perldoc Net::SugarCRM

    perldoc Net::SugarCRM::Tutorial

You can also look for information at:

RT: CPAN's request tracker

http://rt.cpan.org/NoAuth/Bugs.html?Dist=Net-SugarCRM
AnnoCPAN: Annotated CPAN documentation

http://annocpan.org/dist/Net-SugarCRM
CPAN Ratings

http://cpanratings.perl.org/d/Net-SugarCRM
Search CPAN

http://search.cpan.org/dist/Net-SugarCRM/

ACKNOWLEDGEMENTS

Thanks to Phil Hallows Globe Microsystems www.globemicro.com for contributing with get_module_link_ids and get_contact_account_ids the methods

LICENSE AND COPYRIGHT

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.

To install Net::SugarCRM, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Net::SugarCRM

CPAN shell

perl -MCPAN -e shell
install Net::SugarCRM

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

DESCRIPTION

Examples

ATTRIBUTES

url

restuser

restpasswd

globalua

application

email_attr

required_attr

dsn

dbuser

dbpassword

dbh

sessionid

max_results

METHODS

Login/logout

login

encryption

logout

Modules

get_available_modules

get_module_fields

Generic module methods

create_module_entry

get_module_entries

get_module_ids

get_unique_module_id

get_module_entry

get_module_attribute

get_module_entries_from_mail

get_module_ids_from_mail

get_unique_module_id_from_mail

delete_module_entry_by_id

get_module_link_ids

update_module_entry

Lead

create_lead

get_leads

get_lead_ids

get_unique_lead_id

get_lead

get_lead_attribute

get_leads_from_mail

get_lead_ids_from_mail

get_unique_lead_id_from_mail

delete_lead_by_id

update_lead

Contacts

create_contact

get_contacts

get_contact_ids

get_unique_contact_id

get_contact

get_contact_attribute

get_contacts_from_mail

get_contact_ids_from_mail

get_unique_contact_id_from_mail

get_contact_account_ids

delete_contact_by_id

update_contact

Accounts

create_account

get_accounts

get_account_ids

get_unique_account_id

get_account

get_account_attribute

get_accounts_from_mail

get_account_ids_from_mail

get_unique_account_id_from_mail

get_account_contact_ids

delete_account_by_id

update_account

Currency

create_currency

get_currencies