External DataSources

External DataSources are mostly used when you want to retrieve data from an external server and display it together with your Salesforce data. Since the data is retrieved using a user-created Apex Class, it has the advantage of being able to retrieve data more freely than with internal Salesforce data sources.

For example, if you want to fetch real-time inventory numbers from an external server or ERP system, then you can write Rest API code in an Apex Class and point it to an external data source. Then, you will be able to view that data in the Line-Item Configurator.

• Properties

  Describing properties of external DataSources.

• Creating an Apex Class

  Before you can use an external data source, you must write an Apex Class. Implement the SBLD.DataSourceService.Fetchable interface provided by the package by implementing it in the Apex Class you want to write.

• Example

  Under construction.

---

Properties

External DataSource properties are listed below.

Item	Description	Req.
Apex Class Name	The name of the Apex Class used to import external data.	✔️
Key Field	This is the field API name for mapping data which has been retrieved through the DataSource.	✔️
Parent Field Parameters	Represents fields from the Parent object which are to be passed as parameters.
Lookup Field Parameters	Represents fields from the Lookup object which are to be passed as parameters.
Active	Turns the DataSource on or off. It must be active to be used.	✔️

Creating an Apex Class

Before you can use an external data source, you must write an Apex Class. Implement the SBLD.DataSourceService.Fetchable interface provided by the package by implementing it in the Apex Class you want to write.

Classes implementing SBLD.DataSourceService.Fetchable must implement the execute() method.

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 result = new SBLD.DataSourceService.Result();
        /**
         *  @method DataSourceService.Parameter gets()
         *  @param  type String, choose between 'Parent' 
         *          and 'Lookup' (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 to SmallBuilder.
         **/
        for(SObject sobj : lookupRecords) {
            /**
             * Similarly to Internal DataSources, the Action maps a 
             * value from a DataSource to a Lookup or Line-item field. 
             **/
            SBLD.DataSourceServiceAction action = new SBLD.DataSourceServiceAction();
            /** 
             * 1. Set the value of the key from the External DataSource, 
             *    to map to the Lookup or Line-item records.
             **/
            action.setKeyValue(sobj.get('Id')); // e.g. Product Code
            /** 
             * 2. Maps values imported from the External DataSource 
             *    to Lookup or Line-item fields.
             **/
            Map<String, Object> mapPopulatedField = sobj.getPopulatedFieldsAsMap();
            for(String fieldName : mapPopulatedField.keySet()) {
                action.putSourceToTargetField(mapPopulatedField.get(fieldName), fieldName);
            }
            // 3. Add an Action to DataSourceService.Result.
            result.addAction(action);
        }
        return result;
    }
}

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.

// Get data from External Server
HttpRequest request = new HttpRequest();
Request.setMethod(‘POST’);
...
HttpResponse response = new Http().send(request);

List<Object > listResults = (List < Object>)JSON.deserializeUntyped(Response.getBody());

/*Response Body:
[ { itemCode: ‘000001’,  inventory: 3 }, { itemCode: ‘000002’,  inventory: 0 },…  ]

Lookup Record:
[ { Id: ‘XXXXXX1’, ProductCode: ‘000001’, ‘Inventory__c’: null }... ]
*/


...

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')); // e.g. Product Code
    // Populating a Lookup or Line-item field with a value from the External DataSource
    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.