External data sources

External data sources should be used when you want to retrieve data from an external server and present it alongside data from a standard or custom Salesforce object. Since the datasource is accessed using a user-defined Apex class, you can retrieve data more flexibly compared to an internal datasource.

For example, if you want to retrieve real-time inventory numbers from an external system and display them on-screen alongside your product information, you can write REST API code in an Apex Class to do this.

  • Properties

    Describes the properties to be configured when using an external datasource.

  • Creating an Apex class

    Before you can use an external datasource, you must write an Apex class. Your class must implement the SBLD.DataSourceService.Fetchable interface provided in the package.


Properties

There are several properties to be configured when using an external datasource.

Creating an Apex class

Before you can use an external datasource, you must write an Apex class. Your class must implement the SBLD.DataSourceService.Fetchable interface provided in the package.

You must also implement the execute() method in your class.

DataSourceServiceMock.cls
global with sharing class DataSourceServiceMock implements SBLD.DataSourceService.Fetchable {
    /***
     * @description SBLD.DataSourceService.Fetchable execute() definition
     * @param param SBLD.DataSourceService.Parameter parameter type
     *              set by the datasource 
     * @return Map<Object, SObject>
     ****/
    global SBLD.DataSourceService.Result execute(SBLD.DataSourceService.Parameter param) {
        SBLD.DataSourceService.Result results = new SBLD.DataSourceService.Result();
        /**
         *  @method DataSourceService.Parameter gets()
         *  @param  String Parent, choose from Lookups (case insensitive)
         *  @return List<SObject>
         **/
        SObject parentRecord = null;
        List<SObject> lookupRecords = new List<SObject>();
        // Gets Parent-specific parameters.
        if(param.gets('parent')<>null && !param.gets('parent').isEmpty()) {
            parentRecord = param.gets('parent')[0];
        }
        // Gets Lookup-specific parameters.
        if(param.gets('lookup')<>null && !param.gets('lookup').isEmpty()) {
            listLookupParameters = param.gets('lookup');
        }
        /**
         * On success, sets the result to send back to SmallBuilder.
         **/
        for(SObject sobj : lookupRecords) {
            /**
             * Similarly to internal datasources, the Action maps a 
             * value from a datasource to a field in the List's underlying object.
             **/
            SBLD.DataSourceServiceAction action = new SBLD.DataSourceServiceAction();
            // 1. Set the value of the key from the External datasource
            action.setKeyValue(sobj.get('Id')); // Product Code
            // 2. Maps fields from the external datasource to fields in the List's underlying object.
            Map<String, Object> mapPopulatedField = sobj.getPopulatedFieldsAsMap();
            for(String fieldName : mapPopulatedField.keySet()) {
                action.putSourceToTargetField(mapPopulatedField.get(fieldName), fieldName);
            }
            // 3. Add an Action to DataSourceService.Result.
            results.addAction(action);
        }
        return results;
    }
}

You can get information from the Parent or Lookup objects through the gets() method in SBLD.DataSourceService.Parameter

global SBLD.DataSourceService.Result execute(SBLD.DataSourceService.Parameter param) {
    SObject parentRecord = null;
    List<SObject> lookupRecords = new List<SObject>();
    // Gets Parent-specific parameters.
    if(param.gets('parent')<>null && !param.gets('parent').isEmpty()) {
        parentRecord = param.gets('parent')[0];
    }
    // Gets Lookup-specific parameters.
    if(param.gets('lookup')<>null && !param.gets('lookup').isEmpty()) {
        listLookupParameters = param.gets('lookup');
    }
    ...
}

To pass the result to the Line-Item Configurator, we use the class below.

SBLD.DataSourceServiceAction Class

Specifies an Action for each line in the target (Lookup or Line-item). An Action is an operation that maps a DataSource value to a Lookup or Line-item field.

  • setKeyValue(Object keyValue) Sets the Key value to find the target record for the Lookup or Line-item.

  • putSourceToTargetField(Object sourceValue, String targetField) Assigns a data source value to a Lookup or Line-item field.

SBLD.DataSourceService.Result Class

Adds the mapped Action to the return value.

  • addAction(SBLD.DataSourceServiceAction action) Adds an Action to the SBLD.DataSourceService.Result instance.

...
SBLD.DataSourceService.Result result = new SBLD.DataSourceService.Result();
for(Object objResponse : listResponses) {
    Map<String, Object> mapResponse = (Map<String, Object>)objResponse;

    SBLD.DataSourceServiceAction action = new SBLD.DataSourceServiceAction();
    /**
     *  A value that matches the Key field in the DataSource
     *  External Server Key: itemCode,
     *  Lookup Key: ProductCode
     **/    action.setKeyValue(mapResponse.get('Id')); // Product Code
    // Populating a Lookup or Line-item field with a value from the External DataSoure
    action.putSourceToTargetField(mapResponse.get('inventory'), 'Inventory__c');
    // Add an Action to SBLD.DataSourceService.Result.
    result.addAction(action);
}
return result;

Example

Under construction! Contact us if you need further help.

Last updated