Lightning Connect Apex Adaptor

If your organization has already subscribed to the Lighting Connect feature(This is available based on Subscription with additional fees .Contact your salesforce AE to learn more ) to create External Objects,it is good to know that apex can be used by your developer to expose data from any system which uses SOAP or REST as external Objects .

The advantage of using External Objects will be saving some storage space .The data will not reside inside salesforce but can be viewed in salesforce User Interface just like any other objects .

There are number of limitations worth noting before you decide to go with external objects and salesforce documentation can help you in regards to this 

https://help.salesforce.com/HTViewHelpDoc?id=platform_connect_considerations_compatibility.htm&language=en_US 

There are lot of chances that you need data only for reading from external system and may later run apex to convert few into transaction data .One of the ways to address this business use case can be using lightning connect .There may be millions of data and with lightning connect you can keep it outside salesforce but still use salesforce interface to view ,search and use apex to convert some to SFDC native objects .

When lightning connect feature was launched you needed an adaptor to convert data into Odata before you could actually consume and bring into salesforce as an external object.

Its good to know you dont need an Odata now and an apex written by developer can be used by salesforce administrators to bring any data via SOAP or REST to salesforce .

Aim of the blog Post:

   The main aim of this blog post to show an example to developer community on how to extend  data source provider and data source Connection classes to build external data source in salesforce.

We will connect to a simple REST end point available for Non commercial financial  purpose .To explore more about this webservice please read below 

http://www.exchangeratelab.com/docs

Exchangerate Lab provides us free end point for non commercial use to fetch some data that shows latest currency rates for selected Currencies .Please note the aim of calling this webservice is just to demonstrate the Lightning connect feature.

• The first step is to create a DataSource Connection class.

The Connection class will provide 

1. Metadata definition of the external schema which admin of salesforce will generate based on need by just clicking a button
2. Query method to query the data from API.
3. Search method to implement the search via global search
4. Filters and pagination if needed can be implemented in query and search methods
5. Write a JSON parser for mapping data to fields

The below code is self explanatory and it connects to exchangedate labs to fetch currencies and exchange rates

	/**
	* Extends the DataSource.Connection class to enable
	* Salesforce to sync the external system’s metadata schema
	* and to handle queries and searches of the external data.
	**/
	global class CurrencyDataSourceConnection extends DataSource.Connection {
	private DataSource.ConnectionParams connectionInfo;
	/**
	* Constructor for DriveDataSourceConnection.
	**/
	global CurrencyDataSourceConnection(DataSource.ConnectionParams connectionInfo) {
	this.connectionInfo = connectionInfo;
	}
	/**
	* Called when the administrator clicks “Validate and Sync”
	* in the user interface for the external data source.
	**/
	override global List<DataSource.Table> sync() {
	List<DataSource.Table> tables =new List<DataSource.Table>();
	List<DataSource.Column> columns;
	columns = new List<DataSource.Column>();
	columns.add(DataSource.Column.number('rate', 18,6));
	columns.add(DataSource.Column.text('from',10));
	columns.add(DataSource.Column.text('to',10));
	columns.add(DataSource.Column.text('ExternalId',10));
	columns.add(DataSource.Column.url('DisplayUrl',10));
	tables.add(DataSource.Table.get('Currency','ExternalId',columns));
	return tables;
	}
	/**
	* Called to query and get results from the external
	* system for SOQL queries, list views, and detail pages
	* for an external object that’s associated with the
	* external data source.
	*
	* The queryContext argument represents the query to run
	* against a table in the external system.
	*
	* Returns a list of rows as the query results.
	**/
	override global DataSource.TableResult query(DataSource.QueryContext c){
	DataSource.Filter filter = c.tableSelection.filter;
	String url;
	if (filter != null) {
	String cName = filter.columnName;
	if (cName != null && cName.equals('To'))
	url = 'http://api.exchangeratelab.com/api/single/'+filter.columnValue+'?apikey='+Label.API_Key;
	else
	url = 'http://api.exchangeratelab.com/api/current?apikey='+Label.API_Key;
	} else {
	url = 'http://api.exchangeratelab.com/api/current?apikey='+Label.API_Key;
	}
	/**
	* Filters, sorts, and applies limit and offset clauses.
	**/
	List<Map<String, Object>> rows = DataSource.QueryUtils.process(c, getData(url));
	return DataSource.TableResult.get(true, null,c.tableSelection.tableSelected, rows);
	}
	/**
	* Called to do a full text search and get results from
	* the external system for SOSL queries and Salesforce
	* global searches.
	*
	* The searchContext argument represents the query to run
	* against a table in the external system.
	*
	* Returns results for each table that the searchContext
	* requested to be searched.
	* This is to be implemented and not shown in basic Project
	**/
	override global List<DataSource.TableResult> search(DataSource.SearchContext c){
	List<DataSource.TableResult> results =new List<DataSource.TableResult>();
	for (Integer i =0; i< c.tableSelections.size();i++){
	String entity = c.tableSelections[i].tableSelected;
	String url = '';
	results.add(DataSource.TableResult.get(
	true, null, entity, getData(url)));
	}
	return results;
	}
	/**
	* Helper method to parse the data.
	* The url argument is the URL of the external system.
	* Returns a list of rows from the external system.
	**/
	public List<Map<String, Object>> getData(String url){
	HttpResponse response = getResponse(url);
	List<Map<String, Object>> rows =
	new List<Map<String, Object>>();
	Map<String, Object> m = (
	Map<String, Object>)JSON.deserializeUntyped(
	response.getBody());
	system.debug(m);
	String baseCurrency=(String)m.get('baseCurrency');//Get the Base Currency
	/**
	* Checks errors.
	**/
	Map<String, Object> error =
	(Map<String, Object>)m.get('error');
	if (error!=null){
	List<Object> errorsList =
	(List<Object>)error.get('errors');
	Map<String, Object> errors =
	(Map<String, Object>)errorsList[0];
	String ms = (String)errors.get('message');
	throw new DataSource.OAuthTokenExpiredException(ms);
	}
	List<Object> fileItems=(List<Object>)m.get('rates');
	if (fileItems != null){
	for (Integer i=0; i< fileItems.size(); i++){
	Map<String, Object> item =
	(Map<String, Object>)fileItems[i];
	rows.add(createRow(item,baseCurrency));
	}
	} else {
	rows.add(createRow(m,baseCurrency));
	}
	return rows;
	}
	/**
	* Helper method to populate the External ID and Display
	* URL fields on external object records based on the ‘id’
	* value that’s sent by the external system.
	*
	* The item argument maps to the data that
	* represents a row.
	*
	* Returns an updated map with the External ID and
	* Display URL values.
	**/
	public Map<String, Object> createRow(Map<String, Object> item,String baseCurrency){
	Map<String, Object> row = new Map<String, Object>();
	for ( String key : item.keySet() ){
	if (key == 'to') {
	row.put('ExternalId', item.get(key));
	row.put('DisplayUrl', item.get(key));
	row.put('to', item.get(key));
	}
	else{
	row.put(key, item.get(key));
	}
	}
	row.put('from',baseCurrency);
	return row;
	}
	/**
	* Helper method to make the HTTP GET call.
	* The url argument is the URL of the external system.
	* Returns the response from the external system.
	**/
	public HttpResponse getResponse(String url) {
	Http httpProtocol = new Http();
	HttpRequest request = new HttpRequest();
	request.setEndPoint(url);
	request.setMethod('GET');
	HttpResponse response = httpProtocol.send(request);
	return response;
	}
	}

view raw CurrencyDataSourceConnection hosted with ❤ by GitHub

• The next step is to create a Data source Provider class that describes the functional  abilities like authentication mechanism ,capabilities provided by the data source

The below code shows an example class and format 

	/**
	* Extends the DataSource.Provider base class to create a
	* custom adapter for Lightning Connect. The class informs
	* Salesforce of the functional and authentication
	* capabilities that are supported by or required to connect
	* to an external system.
	**/
	global class CurrencyDataSourceProvider extends DataSource.Provider {
	/**
	* Declares the types of authentication that can be used
	* to access the external system
	**/
	override global List<DataSource.AuthenticationCapability> getAuthenticationCapabilities() {
	List<DataSource.AuthenticationCapability> capabilities =new List<DataSource.AuthenticationCapability>();
	//capabilities.add(DataSource.AuthenticationCapability.OAUTH);
	capabilities.add(DataSource.AuthenticationCapability.ANONYMOUS);
	return capabilities;
	}
	/**
	* Declares the functional capabilities that the
	* external system supports.
	**/
	override global List<DataSource.Capability> getCapabilities() {
	List<DataSource.Capability> capabilities =new List<DataSource.Capability>();
	capabilities.add(DataSource.Capability.ROW_QUERY);
	//capabilities.add(DataSource.Capability.SEARCH);
	return capabilities;
	}
	/**
	* Declares the associated DataSource.Connection class.
	**/
	override global DataSource.Connection getConnection(DataSource.ConnectionParams connectionParams) {
	return new CurrencyDataSourceConnection(connectionParams);
	}
	}

view raw CurrencyDataSourceProvider hosted with ❤ by GitHub

The below shows the video on how Admin will configure with simple clicks for magic 

References:

https://help.salesforce.com/HTViewHelpDoc?id=limits_external_data.htm&language=en_US

https://developer.salesforce.com/blogs/engineering/2015/05/introducing-lightning-connect-custom-adapters.html

http://docs.releasenotes.salesforce.com/en-us/summer15/release-notes/rn_forcecom_external_data_apex_adapter.htm

TrailHead Goodness

Most of my friends who come from Java world into apex often ask me about where can they find quick tutorial on CRM lifecycle and quick hands on tutorial on how to use Account Management ,Contact Management ,opportunity management and so on.

TrailHead has got some modules now to explain all of this in depth .

Lets summarize each of the modules and see what they help us learn

Account & Contacts

If you quickly want to learn how to create some Test Accounts and Contacts and understand relationship among them worth spending your half an hour with this module


CRM Basics

Now this may sound silly if you know the concepts but fact is most of developers we dont think of business case for which we spent hours writing code .The basics of salesforce starts with knowing CRM .This module for me should have been first module of TrailHead .Never too late .Grab a coffee and spend some time working on this Trail Badge .


Leads and Opportunities

I would open this module for Training end users .Before we onboard our sales or marketting team ask them to get this badge and I am sure this will help them to gain better understanding on how salesforce will increase their productivity.Explain them the significance of keeping data clean and ask them to create some test data in training environment before they start using the system in their Production Environment .

Event Monitoring

If you are a system architect I would recommend you to learn more about Event Monitoring module .This will give you great insight of how to track various events like login ,logout ,usage of API ,UI clicks .All this will help to draw inference about how the system you have built is being adopted .

Adoption is key metric and this module will help you understand how to pull event log files from SFDC and how to report and analyze reports .

Finally if you are going to dreamforce how cool it is to gather information prior to that and do some homework.Dreamforce module is amazing way to prepare you for this .

If you are a geek and Nerd ,then do some Projects and get hands dirty .Follow the Trailhead Project link below

https://developer.salesforce.com/trailhead/projects

Finally grab all Trailhead badges as I did and beat me up :))