Editor’s Note: This blog post is part of a series of post detailing what’s new from a developer’s perspective in Sugar 6.3. Check out the preview of Sugar 6.3 by downloading it from SugarForge or grabbing it from Github.
With the 6.3 release of Sugar, the Imports module received not only a facelift and complete overhaul for stability but also the ability to import records from external sources such as Google Contacts. In this blog post we’ll examine how the external import components tie together with the existing Sugar framework and discuss at a high level how developers could add custom import sources. Just a fair warning, we won’t outline all of the exact steps necessary in this blog to create a custom import connector but will introduce the general concepts and continue to post further in-depth blogs if requested.
From a general overview, the external import functionality takes advantage of two main architectural components already within Sugar including the connectors framework and the external API. We re-utilize these components because they already handle some of the heavy lifting that is needed when connecting to an external source including authentication and also the data retrieval portion. So the first step then to create a custom import source is to create a class that extends from the ExternalApiBase class and also to create a connector that will be used by this external API module (EAPM). Since this process can be rather involved we will address the necessary steps in a future blog post but you can use the existing Google implementation as a template.
Once your external API module and connector have been created you’ll want to flag the EAPM module to indicate that it supports the Import module so that the Import wizard can pickup and detect this external source. To perform this step, edit your EAPM module and ensure that ‘Import’ is added to the supportedModules instance variable. For example, this is the entry that the current Google implentation has:
public $supportedModules = array('Documents', 'Notes','Import');
Now the Import wizard will list the EAPM as an available external source for Person type modules during the first step of the import process.. Since we have leveraged the externalAPI framework we do not need to worry about authenticating against our service as all those details are handled for us including Oauth authentication!
Now that our import wizard can detect the new external source, we’ll need to handle the data retrieval portion of the equation. We’ll need to implement a single method within our connector where the actual retrieval of data occurs and is eventually handed back to an adapter class within the import wizard. The method that we need to implement is called ‘getList’ and the method signature looks like this:
public function getList($args=array(), $module=null)
The first parameter to the function contains an array which will include the entries ‘maxResults’ and ‘startIndex’. It should be fairly apparent what these two entries represent and they will allow you to support pagination within your getList call. Keep in mind that the import wizard itself will batch requests so that time out limits aren’t hit on either the client or server side. You should expect that multiple calls will be made to your connector so it is essential that you support pagination. It’s in this function that your business logic will reside in to retrieve your data set. For instance, you could simply retrieve a file system stream or perform some sort of web services request.
Once you have implemented the data retrieval portion you’ll now need to create a mapping file for the import wizard. This mapping file will tell the import wizard how to process the result set provided by your connector and to which sugar fields these data points should be mapped to. The mapping file should be placed in ‘modules/Import/maps’ and follows the naming convention ‘ImportMap[EAPM Name].php’. For now you’ll just want to implement the ‘getMapping’ function which returns an array containing mapping entries described as follows:
'external_key' => array('sugar_key' => 'example', 'default_label' => 'I Am An Example'),
By providing the mapping file, the import wizard will automatically be able to provide a default mapping for the end user during the import process to ensure that the import process is as smooth as possible.
Those are the high level steps that are necessary to add a custom external import source. Stay tuned for further in depth posts as we cover step by the step how to create a custom import connector!