Version 5.5.0

Chapter 2 Application Framework

Entry Points

All entry points into the Sugar application are pre-defined so that proper security and authentication steps are applied consistently across the entire application.

•	campaign_tracker.php – used by the Campaign Management module for tracking campaign responses. Deprecated as of Sugar 5.1.0.

•	cron.php – used by the Windows Scheduler Service or the cron service on Linux and Unix for executing the Sugar Scheduler periodically.

•	index.php – default entry point into the Sugar application

•	install.php – used for initial install

•	maintenance.php – invoked when the application is down for maintenance.

•	metagen.php - Deprecated as of Sugar 5.1.0.

•	silentUpgrade.php – used for silent installer

•	soap.php – entry point for all SOAP calls

•	vcal_server.php – used for syncing information to Outlook

Upgrade Implications

One of the many code re-factoring changes we have made starting with Sugar 5.1 is to consolidate the number of entry points into the application as well as rerouting the current entry points through the MVC framework. An entry point is a PHP file that can be called either via URL or command line to actually invoke a Sugar process.  For instance when calling the home page of the application via URL or starting the scheduler via command line.  Consolidating the entry points has also helped us secure the application better and improve quality by making sure each request goes through the same initialization code.

Backwards Compatibility with Custom Code
It does however present some backwards compatibility problems. Most notably you will need to update your code if you have custom code that relies on a deprecated entry point such as a custom Quote template that may have called pdf.php which is no longer a stand-alone entry point. In these cases, you will need to change the URL reference as described below:

1.	Look for the entry point file name in the include/MVC/Controller/entry_point_registry.php. It will be the in the ‘file’ key in the sub-array.

2.	Make note of the key of that array. So for the pdf.php entry point, it appears in include/MVC/Controller/entry_point_registry.php as:

'pdf' => array('file' => 'pdf.php', 'auth' => true),

So we will want to use the ‘pdf’ part in the next step.

3.	Change the URL reference from the current reference to one in the form of:

index.php?entryPoint=<<entrypoint>>

So for the above pdf.php example, we would change our references from

http://<your site>/pdf.php

to:

http://<your site>/index.php?entryPoint=pdf

The only remaining entry points in 5.5 that are not using this new index.php URL pattern (and therefore continue to be valid entry points) are:

•	campaign_tracker.php – used by the Campaign Management module for tracking campaign responses. Deprecated as of Sugar 5.1.0.

•	cron.php – used by the Windows Scheduler Service or the cron service on Linux and Unix for executing the Sugar Scheduler periodically.

•	index.php – default entry point into the Sugar application

•	install.php – used for initial install

•	maintenance.php – invoked when the application is down for maintenance.

•	metagen.php – Deprecated as of Sugar 5.1.0.

•	silentUpgrade.php – used for silent installer

•	soap.php – entry point for all SOAP calls

•	vcal_server.php – used for syncing information to Outlook

File Caching

Much of the user interface is built dynamically via templates from metadata and language string files. SugarCRM implements a file caching mechanism to improve the performance of the system by reducing the number of static metadata and language files that need to be resolved at runtime. This directory stores the cached template and language string files.

When developing in SugarCRM, we suggest that you turn on Developer Mode (Admin->System Settings->Advanced->Developer Mode) which causes the system to ignore these cached files. This is especially helpful when you are altering templates, metadata or language files directly. When using Module Builder or Studio, the system will automatically refresh the file cache. Turn off the Developer Mode when you have completed your customizations because this mode degrades system performance.

Sugar Dashlets

Sugar Dashlets use the abstract factory design pattern. Individual Dashlets extend the base abstract class Dashlet.php, ListView Dashlets extend the base abstract classDashletGeneric.php, while chart Dashlets extend the base abstract class DashletGenericChart.php.

Sugar Dashlet instances must be contained in one of the following directories:

•	modules/moduleName/Dashlets/

•	custom/modules/moduleName/Dashlets/

Typically, Sugar Dashlet developers will want to use the custom/ directory in order to make their Sugar Dashlets upgrade-safe. The standard modules/ directory location is where you'll find Sugar Dashlets offered in base Sugar releases.

Sugar Dashlet Files

The file name containing the main Sugar Dashlet code must match the Sugar Dashlet’s class name. For example, the Sugar Dashlet class JotPadDashlet will be found in the file /Home/Dashlets/JotPadDashlet/JotPadDashlet.php. The JotPadDashlet Dashlet is a sample Sugar Dashlet released originally in Sugar 4.5. It serves as a useful example from which to begin your development efforts.

A metadata file accompanies each Sugar Dashlet. It contains descriptive information about the Sugar Dashlet as defined here:

$DashletMeta['JotPadDashlet'] = array

(

'title' => 'LBL_TITLE',

'description' => 'LBL_TITLE',

'icon' => 'themes/Sugar/images/Accounts.gif',

'category' => 'Tools'

);

The naming convention for the metadata file is className.meta.php, where className is the name of your Sugar Dashlet, and it must appear in the same directory as the Sugar Dashlet code. For JotPadDashlet the meta file is stored in

modules/Home/Dashlets/JotPadDashlet/JotPadDashlet.meta.php.

The ‘title’ and ‘description’ elements are translated. If the values here match a key in the array $DashletStrings (from the language file) then they will be translated otherwise it will display the literal string. (It is best practice to use translatable language strings so that your Sugar Dashlet is international!)

Language files have a similar naming convention: className.locale.lang.php (e.g., /Dashletsmodules/Home/Dashlets/JotPadDashlet/JotpadDashlet.en_us.lang.php )

Icon files can either be defined in the .meta data file or simply included in the Sugar Dashlet Directory (e.g., /Dashletsmodules/Home/Dashlets/JotPadDashlet/JotPadDashlet.icon.png). The system will scan for image files in the corresponding Sugar Dashlet directory.

Templating

The suggested templating engine for Sugar Dashlets is Smarty, however it is not required.

Categories

There are 5 categories for Sugar Dashlets.

•	Module Views – Generic views of data in modules

•	Portal – Sugar Dashlets that allow access to outside data (rss, Web services, etc)

•	Charts – Charts of data

•	Tools – Various tools like a notepad, calculator, or even a world clock!

•	Miscellaneous - Any other Sugar Dashlets

Sugar Dashlet Base Class

The main Sugar Dashlet base class is include/Dashlets/Dashlet.php. All Sugar Dashlets should extend

Each Sugar Dashlet upon creation must be assigned a unique ID. This ID is used as the id for the Sugar Dashlet in the HTML document when it is displayed. This way multiple Sugar Dashlets of the same type can be included on the page.

Sugar Dashlets are stored in the table user_preferences under the name ‘Dashlets’ and the category ‘home’.

The ‘options’ element stores the options for the Sugar Dashlet and this is the element that is loaded/stored by storeOptions / loadOptions functions in the base Dashlet class.

Sugar Dashlets JavaScript

Sugar Dashlet utility functions are located in include/JavaScript/Dashlets.js. This contains the following methods:

postForm: function(theForm, callback) {}

 

postForm method is used to post the configuration form via AJAX. The callback will usually be SUGAR.sugarHome.uncoverPage to remove the configuration dialog.

callMethod: function(DashletId, methodName, postData, refreshAfter, callback) {}

 

callMethod is a generic way to call a method in a Dashlet class. Use this function to generically call a method within your Dashlet class (php side). Optionally, you can refresh your Dashlet after a call and also utilize a callback function.

This method can also be used as a way to proxy AJAX calls to Web services that don’t exist on the SugarCRM install. (Google Maps Mash-ups for example.)

Browser JavaScript

As Sugar is a Web-based application, executing custom logic on the client-side (e.g., validating data before posting it back to the server) requires writing JavaScript. This section outlines the JavaScript constructs available to the developer.

In order to improve application performance, Sugar's production JavaScript files are compressed with the JSMin library. This process reduces JavaScript file sizes, thereby reducing download times. The originally formatted JavaScript files are in the /jssource directory. It is a best practice to make any JavaScript code changes in the /jssource/src_files folders and then use the “Rebuild JS Compressed Files” option in Admin->Repair.

Accessing Language Pack Strings

All language pack strings are accessible within the browser-side JavaScript. To access these strings simply use the following JavaScript call:

// LBL_LOADING string stored in $app_strings

SUGAR.language.get('app_strings', 'LBL_LOADING');

 

// LBL_LIST_LAST_NAME string stored in Contacts $mod_strings

SUGAR.language.get('Contacts', 'LBL_LIST_LAST_NAME');

 

Admins and translators will need to be aware that these JavaScript language files are cached. If there are any changes to the language files they will need to 'rebuild' the JavaScript files from the Repair console in the admin section. This essentially removes the cache files and they will be rebuilt when needed. It also increments js_lang_version in sugar_config so that user's browser will re-cache these js files.

Quicksearch

Sugar 5.1 uses a type-ahead combo box system we call QuickSearch based around ExtJS. The Sugar QuickSearch (SQS) code resides in the file <sugar_root>/include/javascript/quicksearch.js. The ExtJS library which drives the QuickSearch is located at <sugar_root>/include/javascript/ext-2.0/ext-quicksearch.js. These two files are grouped in <sugar_root>/include/javascript/sugar_grp1.js which is loaded in all the main page of SugarCRM. A custom Ext ComboBox is used to pull data via an AJAX call to http://yourserver/SugarCRM/index.php which then accesses the file <sugar_root>/modules/Home/quicksearchQuery.php.

Note: Sugar versions 4.5.1 – 5.0.0 use a system based on wick. Sugar 4.5.0 and prior use <sugar_root>/json_server.php.

The browser will initiate an AJAX call via JavaScript to the server 700ms after the last user input takes place in the browser. A call is then made requesting up to 30 results per result set.

The first twelve results are then displayed to the user in the browser. If the user refines his search and the result set is a subset of the first call then no additional call is made. If the result set of the first call is equal to the limit (30), then an additional call will be made.

Requirement for a QuickSearch Field:

	The class of the field has to be set to "sqsEnabled".

	The field must not be set to "disabled" nor "readOnly".

	The "sqs_objects" JS array has to be defined and has to contain the field name.

	"sugar_grp1.js" has to be loaded on the page.

Custom Parameter :

sqsNoAutofill : add this string to the class of the field to disable the Automatic filling of the field on Blur.

Metadata example:

array(

'name' => 'account_name',

'displayParams' => array(

'hiddeButtons'=>'true',

'size'=>30,

'class'=>'sqsEnabled sqsNoAutofill'

)

),

ACL

ACLs, or Access Control Lists, are used to restrict access to Sugar modules, and the data and actions available (e.g., “Delete” and “Save”) to users within Sugar modules. ACLs are defined in the Roles area of Sugar Admin. Sugar Professional and Enterprise Editions restrict user access down to specific fields.

You can check whether the current user has access to a particular action using the following code:

if (ACLController::checkAccess($category, $action, $is_owner, $type)) {

// your code here

}

 

Where the parameters mean the following:

•	$category = this corresponds to the module directory where the bean resides. For example: Accounts

•	$action – the action you want to check against. For example: edit. These correspond to actions in acl_actions table as well as actions performed by the user within the application.

•	$is_owner – whether or not the owner of the record attempting an action. Defaults to false. This only comes into play when the access level = ALLOW_OWNER

•	$type = this defaults to ‘module’ and for all intents and purposes a developer does not need to pass this in or can pass in ‘module’. This would only be used for special purposes to allow for additional out of the box access levels.

See the ‘Roles’ feature in the Sugar Application Guide for the list of actions and their possible values.

Scheduler

SugarCRM contains a Scheduler service that asynchronously executes predefined functions on a periodic basis. The Scheduler integrates with external UNIX systems and Windows systems to run jobs that are scheduled through those systems. The usual configuration is to have a UNIX cron job or a Windows scheduled job execute the SugarCRM Scheduler service every couple minutes. The Scheduler service checks the list of Schedulers defined in the Scheduler Admin screen and executes any that are currently due.

A series of Schedulers are defined by default with every SugarCRM installation such as “Process Workflow Tasks” and “Run Report Generation Scheduled Tasks”.

Databases

Sugar Community Edition and Sugar Professional Edition support the MySQL and Microsoft SQL Server databases. In addition to these two databases, Sugar Enterprise Edition supports the Oracle database. In general, Sugar uses only common database functionality, and application logic is embedded in the PHP code. This means that Sugar uses no database triggers or stored procedures. This design approach simplifies coding and testing across different database vendors. Therefore the only implementation difference that you will typically find across the various supported databases is column types.

Sugar uses the mysql PHP extension for MySQL support (or mysqli if it enabled), the mssql extension for Microsoft SQL Server support, and the oci8 extension for Oracle support. Sugar does not support generic ODBC access or other database drivers such as PDO.

Indexes

Indexes can be defined directly in the main or custom vardefs.php for module, in an array under the key 'indices'. Below is the example of defining several indices:

'indices' => array (

array(

'name' => 'idx_modulename_name',

'type' => 'index',

'fields' => array('name'),

),

array(

'name' => 'idx_modulename_assigned_deleted',

'type' => 'index',

'fields' => array('assigned_user_id', 'deleted'),

),

),

 

The name of the index should start with idx_ and be unique across the database. The possible values for ‘type’ include 'primary' for a primary key or 'index' for a normal index. The fields list matches the column names used in the database.

Primary Keys, Foreign Keys, and GUIDs

By default, Sugar uses globally unique identification values (GUIDs) for primary keys for all database records. Sugar provides a create_guid() utility function for creating these GUIDs in the following format: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee. The primary key column length is 36 characters.

The GUID format and value has no special meaning in Sugar other than the ability to match records in the DB. Sugar links two records (such as an Account record with a Contact record) with a specified ID in the record type relationship table (e.g. accounts_contacts).

Sugar allows a primary key to contain any unique string. This could either be a different GUID algorithm, a key that has some meaning (such as bean type first, followed by info), an external key, and/or auto-incrementing numbers (converted to strings). The Sugar development team chose GUIDs rather than auto-incrementing keys to allow for easier data synchronization across databases (in order to avoid primary key collisions). This data synchronization issue comes into play when the Sugar Offline Client (part of Sugar Enterprise) syncs data between the main Sugar installation and the Offline Client or when developers use the Sugar SOAP APIs or a tool like Talend for data synchronization.

The strategy of the Offline Client using GUIDs for primary keys is elegant in that it is very easy to implement and handling data conflicts is simpler than with other schemes. If a developer changes Sugar to use some other ID scheme and does need to accommodate data synchronization across data stores, then he would have to either partition the IDs ahead of time or work out a system similar to the Sugar implementation for Cases, Quotes and Bugs. For these modules, which have human-readable ID numbers (integers) that need to be synchronized across databases, Sugar implements a server ID that is globally unique and concatenates that with an incrementing Case, Quotes or Bug number. Attempting such a change to Sugar, while certainly possible, would require some careful planning and implementation.

However if the developer does not need to worry about data synchronization issues, then he can certainly change the primary key format to some other unique string.

Also, it is not a problem to import data from a previous system with one primary key format and then simply have all new records in Sugar use the GUID primary key format. All keys simply need to be stored as unique strings with no more than 36 characters.

To implement a new primary key method or to import existing data with a different primary key format and then rely on the existing GUID mechanism for new records, there are a few things to look out for:

•

The system expects primary keys to be string types and will format the SQL with quotes. If you change the primary key types to an integer type, you might have SQL errors to deal with since we put all ID values in quotes in our generated SQL. The database might be able to ignore this issue. MySQL running in Safe mode will have issues for instance.

•

Case-sensitivity can be an issue. IDs “abc” and “ABC” are typically treated the same in MySQL but represent different values in Oracle. Some other CRM systems from which people were migrating to SugarCRM were using case sensitive strings as their IDs on export. If this is the case, and you are running MySQL, you need to run an algorithm on the data to make sure all of the IDs are unique. One simple algorithm is to MD5 the ids that they provide. A quick check will let you know if there is a problem. If you imported 80,000 leads and there are only 60,000 in the system, some might have been lost due to non-unique primary keys resulting from this case-sensitivity issue.

•

Sugar only tracks the first 36 characters in the primary key. Any replacement primary key will either require changing all of the ID columns with one of an appropriate size or to make sure you don’t run into any truncation or padding issues. MySQL in some versions has had issues with Sugar where the IDs were not matching because it was adding spaces to pad the row out to the full size. MySQL’s handling of char and varchar padding has changed in some of the more recent versions. To protect against this, you will want to make sure the GUIDs are not padded with blanks in the DB.

Logger

The Sugar Logger allows developers and system administrators to log system events and debugging information into a log file. The Sugar code contains log statements at various points, which are triggered based on the logging level.

For example, to write a message to the sugarcrm.log file when the log level is set to ‘fatal’, put the following into your code:

$GLOBALS['log']->fatal('my fatal message');

 

Logger Level

The logger level determines how much information is written to the sugarcrm.log file. You will find the sugarcrm.log file in the root of your Sugar installation.

Valid values are 'debug', 'info', 'error', 'fatal', 'security', and 'off'. The logger will log information for the specified and higher logging levels. For example if you set the log level to 'error' then you would see logs for 'error', 'fatal', and 'security'. You also may define your own log levels on the fly. For example if you set the value to 'test' then only values logged to $GLOBALS['log']->test('This is my test log message'); would be logged. You should avoid using the logging level of ‘off’. The default value is 'fatal'.

$GLOBALS['sugar_config']['logger']['level'] = 'debug';

 

You can also force the log level in your code by using:

$GLOBALS['log']->setLevel('debug');

 

Log File Name

You may concatenate static strings, variables and function calls to set this value. For example if you wish to have monthly logs set this to 'sugarcrm' . date('Y_m') and every day it will generate a new log file. The default value is 'sugarcrm'.

$GLOBALS['sugar_config']['logger']['file']['name']

Log File Extension

The defaults value is '.log'. Therefore the full default log file name is ‘sugarcrm.log’.

$GLOBALS['sugar_config']['logger']['file']['ext']

Log File Date Format

The date format for the log file is any value that is acceptable to the PHP strftime() function. The default is '%c'. For a complete list of available date formats, please see the strftime() PHP documentation.

$GLOBALS['sugar_config']['logger']['file']['dateformat']

 

Max Log File Size

This value controls the max file size of a log before the system will roll the log file. It must be set in the format '10MB' where 10 is number of MB to store. Always use MB as no other value is currently accepted. To disable log rolling set the value to false. The default value is '10MB'.

$GLOBALS['sugar_config']['logger']['file']['maxSize']

Max Number of Log Files

When the log file grows to the 'maxSize' value, the system will automatically roll the log file. The 'maxLogs' value controls the max number of logs that will be saved before it deletes the oldest. The default value is 10.

$GLOBALS['sugar_config']['logger']['file']['maxLogs']

Log Rotation

The Sugar Logger will automatically rotate the logs when the 'maxSize' has been met or exceeded. It will move the current log file to <Log File Name> . 1 . <Log Extension>. If <Log File Name> . 1 . <Log Extension> already exists it will rename it to <Log File Name> . 2 . <Log Extension> prior. This will occur all the way up to the value of 'maxLogs'.

Web Services

SOAP

SugarCRM provides Web Services API’s through the NuSOAP PHP implementation of the SOAP protocol. SOAP stands for "Simple Object Access Protocol." It is used for making Remote Procedure Calls through the HTTP protocol by relaying messages in XML.

The SugarSoap API’s are built using the NuSOAP library and included in the Sugar Community Edition, Sugar Professional Edition and Sugar Enterprise Edition. You can view the SugarSoap API’s at:

http://www.example.com/sugar/service/v2/soap.php

The SugarSoap WSDL (Web Services Description Language) is located at:

http://www.example.com/sugar/service/v2/soap.php?wsdl

Thanks to a myriad of toolkits available, it is easy to make effective use of SOAP Web Services from a variety of programming languages, in particular with Sugar and its wide array of SOAP-based services that it offers.

For these exercises, we will use PHP in conjunction with the NuSOAP Toolkit. You could of course connect to SugarCRM via SOAP and write your application code in Java, C++ or a variety of other SOAP-enabled programming languages.

Note: If the Sugar config.php variables site_url is wrong, SugarSoap will not work. Be sure to verify this value before continuing.

SOAP Protocol

SOAP, a standard Web Services protocol implementation, is a way of exchanging structured information of application functionality. The URL to SOAP is http://localhost/service/v2/soap.php and the URL for WSDL is http://localhost/service/v2/soap.php?wsdl. The WSDL file contains the descriptions for all methods with input/output datatype.

See examples/SugarFullTest_Version2.php for more examples on usage.

Following is the complete SOAP flow.

REST

SugarCRM provides APIs through REST implementation. You can view SugarREST APIs at:

http://www.example.com/sugar/service/v2/rest.php

You can use /service/utils/SugarRest.js to make rest calls using javascript. Look at /service/test.html for examples on how to make REST calls from jaavscript. You can also use curl module to make REST call from server side. Look at the following example

$url = $sugar_config[‘site_url’] . “/service/v2/rest.php”;

$result = doRESTCALL($url, 'login',array('user_auth'=>array('user_name'=>$user_name,'password'=>md5($user_password), 'version'=>'.01'), 'application_name'=>'SoapTest', 'name_value_list' => array(array('name' => 'notifyonsave', 'value' => 'false'))));

function doRESTCALL($url, $method, $data) {

ob_start();

$ch = curl_init();

$headers = (function_exists('getallheaders'))?getallheaders(): array();

$_headers = array();

foreach($headers as $k=>$v){

$_headers[strtolower($k)] = $v;

}

// set URL and other appropriate options

curl_setopt($ch, CURLOPT_URL, $url);

curl_setopt ($ch, CURLOPT_POST, 1);

curl_setopt($ch, CURLOPT_HTTPHEADER, $_headers);

curl_setopt($ch, CURLOPT_HEADER, 1);

curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);

curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 0);

curl_setopt($ch, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_0 );

$post_data = 'method=' . $method . '&input_type=json&response_type=json';

$json = getJSONobj();

$jsonEncodedData = $json->encode($data, false);

$post_data = $post_data . "&rest_data=" . $jsonEncodedData;

curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data);

$result = curl_exec($ch);

curl_close($ch);

$result = explode("\r\n\r\n", $result, 2);

print_r($result[1]);

$response_data = $json->decode($result[1]);

ob_end_flush();

//print_r($response_data);

return $response_data;

 

REST Protocol

Sugar uses the REST protocol to exchange application information. The URL for REST is http://localhost/service/v2/rest.php. The input/output datatype for REST is JSON/PHP serialize. These datatype files, SugarRestJSON.php and SugarRestSerialize.php, are in service/core/REST directory.

You can also define you own datatype. To do this, you need to create a corresponding SugarRestCustomDataType.php file in the service/core/REST directory and override generateResponse() and serve() functions.

The Serve function decodes or unserializes the appropriate datatype based on the input type; the generateResponse function encodes or serializes it based on the output type. See service/test.html for more examples on usage. In this file, the getRequestData function, which generates URL with json, is both the input_type and the response_type. That is, the request data from the javascript to the server is json and response data from server is also json. You can mix and match any datatype as input and output. For example, you can have json as the input_type and serialize as the response_type based on your application’s requirements.

Sugar also provides an example on how to use REST protocol to retrive data from other Sugar instances. In the example, service/example.html uses the SugarRest.server_url variable to make a request to Rest_Proxy.ph, which redirects this request to the appropriate Sugar instance and sends the response back to service/example.html . This server_url varible is a REST URL to other Sugar instances from which you want to retrieve data.

The REST flow is shown below.

API Definitions

SugarCRM provides an application programming interface, Sugar Web Services API, to enable you to customize and extend your Sugar application. Sugar 5.5 provides a new API which offers enhanced performance and provides versioning to help you extend your Sugar application in an upgrade-safe manner.

Versioning

All API classes are located in the Service directory. The URL for the Service directory is http://localhost/service/v2/soap.php. The Service directory contains the following folders:

core – A directory containing the core classes.

REST - A directory containing REST protocols (example, JOSN and PHP serialize classes).

V2 – A directory containing version-specific classes for SOAP and REST implementation. This folder contains the following variables:

$webservice_class – service class responsible for soap services - SugarSoapService2

$webservice_path – The location of the service class - V2/SugarSoapService2.php

$registry_class – Responsible for registering all the complex data types and functions available to call - registry

$registry_path – The location of registry class - service/v2/registry.php

$webservice_impl_class – The implementation class for all the functions – SugarWebServiceImpl

$location – The location of soap.php - '/service/v2/soap.php';

$soap_url – The URL to invoke - $GLOBALS['sugar_config']['site_url'].'/service/v2/soap.php';

Call webservices.php – core/webservice.php is the file which is responsible for instantiating service class and calling different helper methods based on the values of above variables

Core Calls

The supported calls in the API and listed and described in this section.

Call	Description
Call: get_entry()	Retrieves a single SugarBean based on the ID.
Call: get_entries() Call: get_entries()	Retrieves multiple SugarBeans based on IDs. This API is not applicable to the Reports module.
Call: get_entry_list() Call: get_entry_list()	Retrieves a list of SugarBeans.
Call: set_relationship() Call: set_relationship()	Sets a single relationship between two beans where items are related by module name and ID.
Call: set_relationships() Call: set_relationships()	Sets multiple relationships between two beans where items are related by module name and ID.
Call: get_relationship() Call: get_relationship()	Retrieves a collection of beans that are related to the specified bean and, optionally, return relationship data for the related beans.
Call: set_entry() Call: set_entry()	Creates or updates a single SugarBean.
Call: set_entries() Call: set_entries()	Creates or updates a list of SugarBeans.
Call: login() Call: login()	Logs the user into the Sugar application.
Call: logout() Call: logout()	Logs out the user from the current session.
Call: get_server_info() Call: get_server_info()	Obtains server information such as version and GMT time.
Call: get_user_id() Call: get_user_id()	Returns the user_id of the user who is logged into the current session.
Call: get_module_fields() Call: get_module_fields()	Retrieves the vardef information on fields of the specified bean.
Call: seamless_login() Call: seamless_login()	Performs a seamless login. This is used internally during synchronization.
Call: set_note_attachment() Call: set_note_attachment()	Adds or replaces an attachment to a note.
get_note_attachment()	Retrieves an attachment from a note.
Call: set_document_revision() Call: set_document_revision()	Sets a new revision to the document
Call: get_document_revision() Call: get_document_revision()	Allows an authenticated user with the appropriate permission to download a document.
Call: search_by_module() Call: search_by_module()	Returns the ID, module_name, and fields for the specified modules as specified in the search string.
Call: get_available_modules() Call: get_available_modules()	Retrieves the list of modules available to the current user logged into the system.
Call: get_user_team_id() Call: get_user_team_id()	Retrieves the ID of the default team of the user who is logged into the current session.
Call: set_campaign_merge() Call: set_campaign_merge()	Performs a mail merge for the specified campaign.
Call: get_entries_count() Call: get_entries_count()	Retrieves the specified number of records in a module.
Call: get_report_entries() Call: get_report_entries()	Retrieves a list of report entries based on specified report IDs.

 

Call: get_entry()

Retrieves a single SugarBean based on ID.

Syntax

get_entry(session, module_name, id,select_fields, link_name_to_fields_array)

Arguments

Name	Type	Description
session	String	Session ID returned by a previous login call.
module_name	String	The name of the module from which to retrieve records. Note: If you change the module’s tab name in Studio, it does not affect the name that must be passed into this method.
id	String	The SugarBean’s ID.
select_fields	Array	Optional. The list of fields to be returned in the results.
link_name_to_fields_array	Array	A list of link names and the fields to be returned for each link name. Example: 'link_name_to_fields_array' => array(array('name' => 'email_addresses', 'value' => array('id', 'email_address', 'opt_out', 'primary_address')))

Output

Name	Type	Description
entry_list	Array	The record’s name-value pair for the simple datatypes excluding the link field data.
relationship_list	Array	The records link field data.

 

Call: get_entries()

Retrieves a list of SugarBeans based on the specified IDs.

Syntax

get_entries(session, module_name, ids, select_fields, link_name_to_fields_array)

Arguments

Name	Type	Description
session	String	Session ID returned by a previous login call.
module_name	String	The name of the module from which to retrieve records. Note: If you change the module’s tab name in Studio, it does not affect the name that must be passed into this method.
ids	Array	An array of SugarBean IDs.
select_fields	Array	Optional. The list of fields to be returned in the results.
link_name_to_fields_array	Array	A list of link names and the fields to be returned for each link name. Example: 'link_name_to_fields_array' => array(array('name' => 'email_addresses', 'value' => array('id', 'email_address', 'opt_out', 'primary_address')))

Output

Name	Type	Description
entry_list	Array	The record’s name-value pair for the simple datatypes excluding the link field data.
relationship_list	Array	The records link field data.

 

Call: get_entry_list()

Retrieves a list of SugarBeans.

Syntax

get_entry_list(session, module_name, query, $order_by,offset, select_fields, link_name_to_fields_array, max_results, deleted)

Arguments

Name	Type	Description
session	String	Session ID returned by a previous login call.
module_name	String	The name of the module from which to retrieve records. Note: If you change the module’s tab name in Studio, it does not affect the name that must be passed into this method.
query	String	The SQL WHERE clause without the word “where”.
order_by	String	The SQL ORDER BY clause without the phrase “order by”.
offset	String	The record offset from which to start.
select_fields	Array	Optional. A list of fields to include in the results.
link_name_to_fields_array	Array	A list of link names and the fields to be returned for each link name. Example: 'link_name_to_fields_array' => array(array('name' => 'email_addresses', 'value' => array('id', 'email_address', 'opt_out', 'primary_address')))
max_results	String	The maximum number of results to return.
deleted	Number	To exclude deleted records

Output

Name	Type	Description
result_count	Integer	The number of returned records.
next_offset	Integer	The start of the next page.
entry_list	Array	The records that were retrieved.
relationship_list	Array	The records’ link field data.

 

Call: set_relationship()

Sets a single relationship between two SugarBeans.

Syntax

set_relationship(session, module_name, module_id, link_field_name, related_ids)

Arguments

Name	Type	Description
session	String	Session ID returned by a previous login call.
module_name	String	The name of the module from which to retrieve records. Note: If you change the module’s tab name in Studio, it does not affect the name that must be passed into this method.
module_id	String	The ID of the specified module bean.
link_field_name	String	The name of the field related to the other module.
related_ids	Array	IDs of related records

Output

Name	Type	Description
created	Integer	The number of relationships that were created.
failed	Integer	The number of relationships that failed.
deleted	Integer	The number of relationships that were deleted.

 

Call: set_relationships()

Sets multiple relationships between two SugarBeans.

Syntax

set_relationships(session, module_names, module_ids, link_field_names, related_ids)

Arguments

Name	Type	Description
session	String	Session ID returned by a previous login call.
module_names	Array	The name of the module from which to retrieve records. Note: If you change the module’s tab name in Studio, it does not affect the name that must be passed into this method.
module_ids	Array	The ID of the specified module bean.
link_field_names	Array	The name of the field related to the other module.
related_id	Array	IDs of related records

Output

Name	Type	Description
created	Integer	The number of relationships that were created.
failed	Integer	The number of relationships that failed.
deleted	Integer	The number of relationships that were deleted.

 

Call: get_relationship()

Retrieves a collection of beans that are related to the specified bean and, optionally, returns relationship data.

Syntax

get_relationships(session, module_name, module_id, link_field_name, related_module_query, related_fields, related_module_link_name_to_fields_array, deleted)

Arguments

Name	Type	Description
session	String	Session ID returned by a previous login call.
module_name	String	The name of the module from which to retrieve records. Note: If you change the module’s tab name in Studio, it does not affect the name that must be passed into this method.
module_ids	String	The ID of the specified module bean.
link_field_name	String	The relationship name of the linked field from which to return records.
related_module_query	String	The portion of the WHERE clause from the SQL statement used to find the related items.
related_fields	Array	The related fields to be returned.
related_module_link_name_to_fields_array	Array	For every related bean returned, specify link field names to field information. Example: 'link_name_to_fields_array' => array(array('name' =>'email_addresses', 'value' => array('id', 'email_address', 'opt_out', 'primary_address')))
deleted	Number	To exclude deleted records

Output

Name	Type	Description
entry_list	Array	The records that were retrieved.
relationship_list	Array	The records’ link field data.

 

Call: set_entry()

Creates or updates a SugarBean.

Syntax

set_entry(session,module_name, name_value_list)

Arguments

Name	Type	Description
session	String	Session ID returned by a previous login call.
module_name	String	The name of the module from which to retrieve records. Note: If you change the module’s tab name in Studio, it does not affect the name that must be passed into this method.
name_value_list	Array	The value of the SugarBean attributes

Output

Name	Type	Description
id	String	The ID of the bean that that was written to.

 

Call: set_entries()

Creates or updates a list of SugarBeans.

Syntax

set_entries(session,module_name, name_value_lists)

Arguments

Name	Type	Description
session	String	Session ID returned by a previous login call.
module_name	String	The name of the module from which to retrieve records. Note: If you change the module’s tab name in Studio, it does not affect the name that must be passed into this method.
name_value_lists	Array	An array of bean-specific arrays where the keys of the array are SugarBean attributes.

Output

Name	Type	Description
ids	String	The IDs of the beans that that were written to.

 

Call: login()

Logs the user into the Sugar application.

Syntax

login(user_auth, application)

Arguments

Name	Type	Description
user_auth	Array	Sets username and password
application	String	Not used. The name of the application from which the user is loggin in.
name_value_list	Array	Sets the name_value pair. Currently you can use this function to set values for the ‘language’ and ‘notifyonsave’ parameters. The language parameter sets the language for the session. For example, ‘name’=’language’, ‘value’=’en_US’ The ‘notifyonsave sends a notification to the assigned user when a record is saved. For example, ‘name’=’notifyonsave’,’value’=’true’.

Output

Name	Type	Description
id	String	The session ID
module_name	String	The Users module
name_value_list	Array	The name-value pair of user ID, user name, and user language, user currency ID, and user currency name.

 

Call: logout()

Logs out of the Sugar user session.

Syntax

logout($session)

Example:

To log out a user:

logout array('user_auth' =>

array('session'=>' 4d8d6c12a0c519a6eff6171762ac252c')

Arguments

Name	Type	Description
session	String	Session ID returned by a previous call to login.

This call does not return an output.

 

Call: get_server_info()

Returns server information such as version, flavor, and gmt_time.

Syntax

get_server_info()

Arguments

Name	Type	Description
None	Null	No Arguments

Output

Name	Type	Description
flavor	String	Sugar edition such as Enterprise, Professional, or Community Edition.
version	String	The version number of the Sugar application that is running on the server.
gmt_time	String	The current GMT time on the server in Y-m-d H:i:s format.

 

Call: get_user_id()

Returns the ID of the user who is logged into the current session.

Syntax

new_get_user_id array('session' => sessionid)

Arguments

Name	Type	Description
session	String	Returns the User ID of the current session

Output

Name	Type	Description
user id	String	The user ID

 

Call: get_module_fields()

Retrieves variable definitions (vardefs) for fields of the specified SugarBean.

Syntax

get_module_fields(session, module_name, fields)

Arguments

Name	Type	Description
session	String	Returns the session ID
module_name	String	The module from which to retrieve vardefs.
fields	Array	Optional. Returns vardefs for the specified fields.

Output

Name	Type	Description
module_fields	Array	The vardefs of the module fields.
link_fields	Array	The vardefs for the link fields.

 

Call: seamless_login()

Performs a seamless login during synchronization.

Syntax

seamless_login(session)

Arguments

Name	Type	Description
session	String	Returns the session ID

Output

Name	Type	Description
1	Integer	If the session is authenticated
0	Integer	If the session is not authenticated

 

Call: set_note_attachment()

Add or replace a note’s attachment. Optionally, you can set the relationship of this note to related modules using related_module_id and related_module_name.

Syntax

set_note_attachment(session, note)

Arguments

Name	Type	Description
session	String	The session ID returned by a previous call to login.
note	Array	The ID of the note containing the attachment.
filename	String	The file name of the attachment.
file	Binary	The binary contents of the file.
related_module_id	String	The id of the module to which this note is related.
related_module_name	String	The name of the module to which this note is related.

Output

Name	Type	Description
id	String	The ID of the note.

get_note_attachment()

Retrieves an attachment from a note.

Syntax

get_note_attachment(session,id)

Arguments

Name	Type	Description
session	String	The ID of the session
id	String	The ID of the note.

Output

Name	Type	Description
id	String	The ID of the note containing the attachment.
filename	String	The file name of the attachment.
file	Binary	The binary contents of the file.
related_module_id	String	The id of the module to which this note is related.
related_module_name	String	The name of the module to which this note is related.

 

Call: set_document_revision()

Sets a new revision for a document.

Syntax

set_document_revision(session, document_revision)

Arguments

Name	Type	Description
session	String	Returns the session ID
document_revision	String	The document ID, document name, the revision number, the file name of the attachment, the binary contents of the file.
id	String	The document revision ID.

Output

Name	Type	Description
id	String	The ID of the document revision.

 

Call: get_document_revision()

In case of .htaccess lock-down on the cache directory, allows an authenticated user with the appropriate permissions to download a document.

Syntax

get_document_revision(session, id)

Arguments

Name	Type	Description
session	String	Returns the session ID
id	String	The ID of the revised document

Output

Name	Type	Description
document_revision_id	String	The ID of the document revision containing the attachment.
document_name	String	The name of the revised document
revision	String	The revision value
filename	String	The file name of the attachment
file	Binary	The binary contents of the file.

 

Call: search_by_module()

Returns the ID, module name and fields for specified modules. Supported modules are Accounts, Bugs, Calls, Cases, Contacts, Leads, Opportunities, Projects, Project Tasks, and Quotes.

Syntax

search_by_module(session, search_string, modules, offset, max_results)

Arguments

Name	Type	Description
session	String	The session ID returned by a previous call to login
search_string	String	The string to search for
modules	String	The modules to query
offset	Integer	The specified offset in the query
max_results	Integer	The maximum number of records to return

Output

Name	Type	Description
return_search_result	Array	The records returned by the search results.

 

Call: get_available_modules()

Retrieves the list of modules available to the current user logged into the system.

Syntax

get_available_modules (session)

Arguments

Name	Type	Description
session	String	The session ID returned by a previous call to login

Output

Name	Type	Description
modules	Array	An array of available modules

 

Call: get_user_team_id()

Retrieves the ID of the default team of the user who is logged into the current session.

Syntax

get_user_team_id (session)

Arguments

Name	Type	Description
session	String	The session ID returned by a previous call to login

Output

Name	Type	Description
team_id	String	The ID of the current user’s default team.

 

Call: set_campaign_merge()

Performs a mail merge for the specified campaign.

Syntax

set_campaign_merge (session,targets,campaign_id)

Arguments

Name	Type	Description
session	String	The session ID returned by a previous call to login
targets	Array	A string array of IDs identifying the targets used in the merge.
campaign-id	String	The campaign ID used for the mail merge.

This call does not return an output.

 

Call: get_entries_count()

Retrieves the specified number of records in a module.

Syntax

get_entries_count(session, module_name,query, deleted)

Arguments

Name	Type	Description
session	String	The session ID returned by a previous call to login
module_name	String	The name of the module from which to retrieve the records
query	String	Allows the webservice user to provide a WHERE clause.
deleted	Integer	Specifies whether or not to include deleted records.

Output

Name	Type	Description
result_count	Integer	Total number of records for the specified query and module

 

Call: get_report_entries()

(Sugar Enterprise and Professional only)

Retrieves a list of report entries based on specified report IDs.

Syntax

get_report_entries(session,ids,select_fields)

Arguments

Name	Type	Description
session	String	The session ID returned by a previous call to login
ids	Array	The array of report IDs.
select_fields	String	Optional. The list of fields to be included in the results. This parameter enables you to retrieve only required fields.

Output

Name	Type	Description
field_list	String	Vardef information about the returned fields.
entry_list	String	Array of retrieved records.

Sample Request For User Login

Sample Request

<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sug="http://www.sugarcrm.com/sugarcrm">

<soapenv:Header/>"

<soapenv:Body>"

<sug:login soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">"

<user_auth xsi:type="sug:user_auth">

<!--You may enter the following 2 items in any order-->

<user_name xsi:type="xsd:string">admin</user_name>

<password xsi:type="xsd:string">0cc175b9c0f1b6a831c399e269772661

</password>"

</user_auth>

<application_name xsi:type="xsd:string"/>

</sug:login>

</soapenv:Body>

</soapenv:Envelope>

Sample Response

<SOAP-ENV:Envelope SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:tns="http://www.sugarcrm.com/sugarcrm">

<SOAP-ENV:Body>

<ns1:loginResponse xmlns:ns1="http://www.sugarcrm.com/sugarcrm">

<return xsi:type="tns:entry_value">

<id xsi:type="xsd:string">5b7f9c396370d1116affa5f863695c60</id>

<module_name xsi:type="xsd:string">Users</module_name>

<name_value_list xsi:type="SOAP-ENC:Array" SOAP-ENC:arrayType="tns:name_value[5]">

<item xsi:type="tns:name_value">

<name xsi:type="xsd:string">user_id</name>

<value xsi:type="xsd:string">1</value>

</item>

<item xsi:type="tns:name_value">

<name xsi:type="xsd:string">user_name</name>

<value xsi:type="xsd:string">admin</value>

</item>

<item xsi:type="tns:name_value">

<name xsi:type="xsd:string">user_language</name>

<value xsi:type="xsd:string">en_us</value>

</item>

<item xsi:type="tns:name_value">

<name xsi:type="xsd:string">user_currency_id</name>

<value xsi:nil="true" xsi:type="xsd:string"/>

</item>

<item xsi:type="tns:name_value">

<name xsi:type="xsd:string">user_currency_name</name>

<value xsi:type="xsd:string">US Dollars</value>

</item>

</name_value_list>

</return>

</ns1:loginResponse>

</SOAP-ENV:Body>

</SOAP-ENV:Envelope>

 

Extensibility in Upgrade Safe Manner

In the previous version of Sugar, people extended the application by modifying the out-of-the-box php files to provide their own functionality. However, if you upgraded to a newer version you lost the customized functionality. Hence, it was not upgrade safe.

The 5.5.0 release provides versioning for upgrade safe extensibility (Please refer to the Versioning section for details).

Follow the steps outlined below to create your own upgrade-safe version.

1)	The services directory contains a v2 directory. Create a v2_1 directory in the custom directory. You can create this directory anywhere in the directory structure of source code but it is best to put it in the custom directory so that it is upgrade safe.

2)	You need to provide your own registry.php. For example,. customregistry.php, and the source code looks like this:

<?php

require_once('service/v2/registry.php');

class customregistry extends registry{

public function __construct($serviceClass) {

parent::__construct($serviceClass);

} // fn

protected function registerFunction() {

parent::registerFunction();

$this->serviceClass->registerFunction(

'get_entry',

array('session'=>'xsd:string', 'module_name'=>'xsd:string', 'id'=>'xsd:string'),

array('return'=>'xsd:string'));

 

} // fn

} // class

3)	Look at the registerFunction. We call parent:: registerFunction() to include all the out of box functions and the next line is $this->serviceClass->registerFunction(name, input, output). This allows you to provide your own functions.

4)	You need to provide you own implementation class which extends from the base implementation class. For example.

<?php

require_once('service/core/SugarWebServiceImpl.php');

class SugarWebServiceImpl_v2_1 extends SugarWebServiceImpl {

function get_entry($session, $module_name, $id){

return $id;

} // fn

} // class

5)	You need to provide you own soap.php or rest.php and initialize all the variables.

The following is an example of your own soap.php

<?php

Chdir(‘../’) (based on how much deep you have defines v2_1 directory)

$webservice_class = 'SugarSoapService2';

$webservice_path = 'service/v2/SugarSoapService2.php';

$registry_class = ' customregistry ';

$registry_path = 'service/v2_1/ customregistry.php';

$webservice_impl_class = 'SugarWebServiceImpl_v2_1';

$location = '/service/v2_1/soap.php';

require_once('../core/webservice.php');

?>

Now your new SOAP URL will be http://localhost/service/v2_1/soap.php.

Following is an example of your rest.php

<?php

Chdir(‘../’) (based on how much deep you have defines v2_1 directory)

$webservice_class = 'SugarRestService2';

$webservice_path = 'service/v2/SugarRestService2.php';

$registry_class = ' customregistry ';

$registry_path = 'service/v2_1/ customregistry.php';

$webservice_impl_class = 'SugarRestServiceImpl_v2_1';

$location = '/service/v2_1/rest.php';

require_once('../core/webservice.php');

?>

Now your new REST URL will be http://localhost/service/v2_1/rest.php. Your v2_1 directory is now upgrade safe.

SOAP Errors

We will set the fault object on server in case of any exception. So the client has to check for errors and call the appropriate method to get the error code and description from that object

Support WS-I 1.0Basic profile for WSDL

Sugar has provided support to generate a URL that is WS-I compliant. to access theWSDL file in the format http://<hostname>/service/v2/soap.php?wsdl.

Hence, the new URL will look like this: http://<hostname>/service/v2/soap.php?wsdl&style=rpc&use=literal. The style parameter can take either 'rpc' or 'document' and use parameter can be 'literal' or 'encoded'. If you don't specify style and use parameter then default will be rpc/encoded.

We successfully tested this WSDL (rpc/literal) with Apache CXF 2.2.

SugarSoap Examples

See examples/SoapFullTest_Version2.php for soap examples.

Note: it is also possible to create a NuSOAP client as follows without requiring the WSDL:

$ soapclient = new nusoapclient('http://www.example.com/sugar/soap.php’,false);

 

This speeds up processing because downloading the WSDL before invoking the method is time intensive. This type of URL (http://www.example.com/sugar/soap.php) without havin ?wsdl at the end work fine with NUSOAP client. But with clients like .net, java you need to generate all the client side classes for all the complex type data types by giving appropriate WSDL (rpc or document and literal and encoded) and make a service call by coding it to those generated classes.

Cloud Connectors Framework

Introduction

This section covers the design specifications for the connector integration capabilities in SugarCRM called “Cloud Connectors”. The Cloud Connector framework allows for various data retrieved through REST and SOAP protocols to be easily viewed and entered into SugarCRM.

The Cloud Connector framework is designed to provide an abstract layer around a connector. So, essentially our own database would just be considered another connector along with any Soap or, REST connector. These connectors, in theory, can then be swapped in and out seamlessly. Now we all know, at least at this point, this is not the reality, but providing the framework for it and leveraging a small component will be a step in the right direction. These connectors can then be loaded in by a factory and returned and called based on their interface methods.

The main components for the connector framework are the factories, source and formatter classes. The factories are responsible for returning the appropriate source or formatter instance for a connector. The sources are responsible for encapsulating the retrieval of the data as a single record or a list or records of the connectors. The formatters are responsible for rendering the display elements of the connectors.

Factories

The primary factory is the ConnectorFactory class. It uses the static SourceFactory class to return a connector instance.

The main points to note are that given a source name (e.g. "ext_soap_hoovers"), the underscore characters are replaced with the file separator character. In this case, "ext_soap_hoovers" becomes "ext/soap/hoovers". Then the SourceFactory scans in order the modules/Connectors/connectors/sources first and then the custom/modules/Connectors/connectors/sources directories to check for the presence of this file and returns a source instance if the file is found. The following sequence diagram attempts to highlight the aforementioned steps.

There is also the FormatterFactory class to return a formatter instance. Retrieving a formatter instance is similar to retrieving a source instance except that the FormatterFactory scans in order the modules/Connectors/connectors/formatters first and then the custom/modules/Connectors/connectors/formatters directories.

Sources

The sources are the centerpiece of the connectors framework. There are two categories of sources- REST implementations and SOAP implementations. The default source class is abstract and subclasses need to override the getList and getItem methods. The class name of the source should be prefixed with either "ext_soap_" or "ext_rest_". This is because the "_" character serves as a delimiter into the file system for the class to be found. For example, a SOAP implementation for a source we call "Test" will have the class name "ext_soap_test" and a REST implementation will have the class name "ext_rest_test".

/**

* getItem

* Returns an array containing a key/value pair(s) of a source record

*

* @param Array $args Array of arguments to search/filter by

* @param String $module String optional value of the module that the connector framework is attempting to map to

* @return Array of key/value pair(s) of the source record; empty Array if no results are found

*/

public function getItem($args=array(), $module=null){}

 

/**

* getList

* Returns a nested array containing a key/value pair(s) of a source record

*

* @param Array $args Array of arguments to search/filter by

* @param String $module String optional value of the module that the connector framework is attempting to map to

* @return Array of key/value pair(s) of source record; empty Array if no results are found

*/

public function getList($args=array(), $module=null){}

 

Here is an example of the Array format for the getItem method of the Test source:

Array(

['id'] => 19303193202,

['duns'] => 19303193202,

['recname'] => 'SugarCRM, Inc',

['addrcity'] => 'Cupertino',

)

 

Here is an example of the Array format for the getList method of the Test source:

Array(

[19303193202] => Array(

['id'] => 19303193202,

['duns'] => 19303193202,

['recname'] => 'SugarCRM, Inc',

['addrcity'] => 'Cupertino',

),

[39203032990] => Array(

['id'] => 39203032990,

['duns'] => 39203032990,

['recname'] => 'Google',

['addrcity'] => 'Mountain View',

)

)

The key values for the getList/getItem entries should be mapped to a vardefs.php file contained with the source. This vardefs.php file is required. In this case, we have something like:

<?php

$dictionary['ext_rest_test'] = array(

'comment' => 'vardefs for test connector',

'fields' => array (

'id' => array (

'name' => 'id',

'vname' => 'LBL_ID',

'type' => 'id',

'hidden' => true

'comment' => 'Unique identifier'

),

'addrcity' => array (

'name' => 'addrcity',

'input' => 'bal.location.city',

'vname' => 'LBL_CITY',

'type' => 'varchar',

'comment' => 'The city address for the company',

'options' => 'addrcity_dom',

'search' => true,

),

)

);

?>

Note the 'input' key for the addrcity entry. The 'input' key allows for some internal argument mapping conversion that the source uses. The period (.) is used to delimit the input value into an Array. In the example of the addrcity entry, the value bal.location.city will be translated into the Array argument ['bal']['location']['city'].

The 'search' key for the addrcity entry may be used for the search form in the connector data merge wizard screens available for the professional and enterprise editions.

Finally, note the 'options' key for the addrcity entry. This 'options' key maps to an entry in the mapping.php file to assist in the conversion of source values to the database value format in SugarCRM. For example, assume a source that returns a American city values as a numerical value (San Jose = 001, San Francisco = 032, etc.). Internally, the SugarCRM system may use the city airport codes (San Jose = sjc, San Francisco = sfo). To allow the connector framework to map the values, the options configuration is used.

Sources also need to provide a config.php file that may contain optional runtime properties such as the URL of the SOAP WSDL file, API keys, etc. These runtime properties shall be placed under the 'properties' Array. At a minimum, a 'name' key should be provided for the source.

<?php

$config = array (

'name' => 'Test', //Name of the source

'properties' =>

array (

'TEST_ENDPOINT' => 'http://test-dev.com/axis2/services/AccessTest',

'TEST_WSDL' => 'http://hapi-dev.test.com/axis2/test.wsdl',

'TEST_API_KEY' => 'abc123',

),

);

?>

An optional mapping.php file may be provided so that default mappings are defined. These mappings assist the connector framework's component class. In the component class there are the fillBean and fillBeans methods. These methods use the getItem/getList results from the source instance respectively and return a SugarBean/SugarBeans that map the resulting values from the source to fields of the SugarBean(s). While the mapping.php file is optional, it should be created if the 'options' key is used in vardefs entries in the vardefs.php file.

<?php

$mapping = array (

'beans' => array (

'Leads' => array (

'id' => 'id',

'addrcity' => 'primary_address_city',

),

'Accounts' => array (

'id' => 'id',

'addrcity' => 'primary_address_city',

),

),

'options' => array (

'addrcity_dom' => array (

'001' => 'sjc', //San Jose

'032' => 'sfo', //San Francisco

),

),

);

?>

In this example, there are two modules that are mapped (Leads and Accounts). The source keys are the Array keys while the SugarCRM module's fields are the values. Also note the example of the 'options' Array as discussed in the vardefs.php file section. Here we have defined an addrcity_dom element to map numerical city values to airport codes.

The source file (test.php) and its supporting files will be placed into self contained directories. In our test example, the contents would be as follows:

*custom/modules/Connectors/connectors/sources/ext/rest/test/test.php

*custom/modules/Connectors/connectors/sources/ext/rest/test/vardefs.php

*custom/modules/Connectors/connectors/sources/ext/rest/test/config.php

*custom/modules/Connectors/connectors/sources/ext/rest/test/mapping.php

 

Formatters

The optional formatter components are used by the connector framework to render a popup window that may display additional details and information. Currently, they are shown in the detail view screens for modules that are enabled for the connector. Like the source class, the formatter class has a corresponding factory class (FormatterFactory). The formatters also follow the same convention of using the "ext_rest_" or "ext_soap_" prefix. However, to distinguish conflicting class names, a suffix "_formatter" is also used. Formatters extend from default_formatter.

The following class diagram shows an example of the LinkedIn formatter extending from the default formatter.

Here, we have a subclass ext_rest_linkedin_formatter that overrides the getDetailViewFormat and getIconFilePath methods.

require_once('include/connectors/formatters/default/formatter.php');

 

class ext_rest_linkedin_formatter extends default_formatter {

public function getDetailViewFormat() {

$mapping = $this->getSourceMapping();

$mapping_name = !empty($mapping['beans'][$this->_module]['name']) ? $mapping['beans'][$this->_module]['name'] : '';

 

if(!empty($mapping_name)) {

$this->_ss->assign('mapping_name', $mapping_name);

return $this->fetchSmarty();

}

 

$GLOBALS['log']->error($GLOBALS['app_strings']['ERR_MISSING_MAPPING_ENTRY_FORM_MODULE']);

return '';

}

 

public function getIconFilePath() {

return 'modules/Connectors/connectors/formatters/ext/rest/linkedin/tpls/linkedin.gif';

}

 

}

 

The default_formatter class provides an implementation of the getDetailViewFormat method. This method is responsible for rendering the hover code that appears next to certain detail view fields. The default_formatter class will scan the tpls directory for a Smarty template file named after the module that is being viewed. For example, the file *formatters/ext/rest/linkedin/tpls/Accounts.tpl will be used for the Accounts popup view if the file exists. If the module named template file is not found , it will attempt to use a file named default.tpl.

Formatters are invoked from the Smarty template code which in turn uses Smarty plugins to call the Formatter classes. The following sequence diagram illustrates this.