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.

• Example

---

Properties

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

Apex class for an external datasource

Flow for an external datasource

Field name or area	Description	Req.
Select the type of external connection.	There are two ways to connect to external datasources. Apex - use an Apex class that implements the SBLD.DataSourceService.Fetchable interface. Flow - use an automatically executing Flow.	✔️
Enable	Enables the datasource. A disabled datasource will not be available when building custom lists.
Description	Provide a description of your datasource.
Key Field	Specifies which fields from the List object should be matched with fields from the datasource.	✔️
Parameters	If your datasource needs to be passed values from fields in the List object, select those fields here.
Input Variable	Select the parameter variables to pass to the Flow. If no parameters are required, leave unchecked. 💡 The displayed options are those marked "Available for input" in the Flow.
Output Variable	Select the variables to receive the results from the Flow. 💡 The displayed options are those marked "Available for output" in the Flow.	✔️

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.