The sources are the centerpiece of the Connectors framework. There are two categories of sources - REST implementations andSOAP 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 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 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 Connectors’ data merge wizard screens available for the Ultimate, Enterprise, Corporate, and Professional 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 American city values as a numerical value (San Jose = 001, San Francisco = 032, etc.). Internally, the Sugar 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 Sugar 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
