Advanced: Retrieve Data Using Apex Classes

Use the Advanced DataSource feature when you need to fetch data from external API servers or perform complex logic for data retrieval and merging. To set up Advanced DataSource, you must write an Apex Class. This approach provides greater flexibility compared to the Basic DataSource for fetching and processing data.

1

Writing an Apex Class

When writing an Apex class, you must implement the interface provided by SmallBuilder.

2

Advanced Data Source Configuration

Once the Apex class implementation is complete, proceed with the Advanced Data Source Configuration in the builder.

STEP 1: Implement the Interface for Writing an Apex Class

To use an Apex Class with Advanced DataSource, you must implement the SBLI.DataSourceService.Fetchable interface.

This interface includes the execute method, where you implement logic for processing data and returning an SBLI.DataSourceService.Result object. The result contains mapping information between the fetched data and the Lookup or Line Item objects.

Example Code

The following example assumes an external API is called to retrieve inventory quantities by product code. The data is then mapped to the Inventory__c field in the Lookup or Line Item object.

The SBLI.DataSourceService.Fetchable interface is provided by the package. Both the Apex class and the methods must be declared as global to allow external access.

global class DataSourceInventory implements SBLI.DataSourceService.Fetchable {
    global SBLI.DataSourceService.Result execute(SBLI.DataSourceService.Parameter params) {
        // Fetch parent record
        SObject parentRecord = params.getParentRecord();

        // Fetch lookup records
        List<SObject> lookupRecords = params.getLookupRecords();
        
        // Fetch data from external API (e.g., inventory information)
        // Key: Product Code, Value: Inventory Quantity
        Map<String, Integer> inventoryData = new Map<String, Integer>(); 
        inventoryData.put('Product001', 10);
        inventoryData.put('Product002', 20);

        // Create result object
        SBLI.DataSourceService.Result result = new SBLI.DataSourceService.Result();

        // Map DataSource values to Lookup/Line Item objects
        for (String productCode : inventoryData.keySet()) {
            SBLI.DataSourceService.Action action = new SBLI.DataSourceService.Action();
            action.setKeyValue(productCode); // Set Key value for mapping with Lookup/Line Item records
            action.putSourceToTargetField(
                inventoryData.get(productCode), // DataSource value: inventory quantity
                'Inventory__c'                 // API name of the target field in Lookup/Line Item
            );
            result.addAction(action); // Add Action to the result
        }
        
        return result; // Return result
    }
}

1

Fetch Parent and Lookup Records

• params.getParentRecord(): Retrieves the parent record of the object.

• params.getLookupRecords(): Retrieves the list of records from the Lookup object.

// Fetch parent record
SObject parentRecord = params.getParentRecord();
// Fetch lookup records
List<SObject> lookupRecords = params.getLookupRecords();

2

Prepare DataSource Values

• Data is fetched from an external API server (e.g., inventory information).

• In the example, inventory quantities are mapped based on ProductCode.

Map<String, Integer> inventoryData = new Map<String, Integer>(); 
inventoryData.put('Product001', 10);
inventoryData.put('Product002', 20);

3

Generate Result

• An SBLI.DataSourceService.Action object is created to map the fetched data (e.g., inventory quantity) to the target field (Inventory__c).

• The action is added to the SBLI.DataSourceService.Result object.

// Create result object
SBLI.DataSourceService.Result result = new SBLI.DataSourceService.Result();

// Map DataSource values to Lookup/Line Item objects
for (String productCode : inventoryData.keySet()) {
    SBLI.DataSourceService.Action action = new SBLI.DataSourceService.Action();
    action.setKeyValue(productCode); // Set Key value for mapping with Lookup/Line Item records
    action.putSourceToTargetField(
        inventoryData.get(productCode), // DataSource value: inventory quantity
        'Inventory__c'                 // API name of the target field in Lookup/Line Item
    );
    result.addAction(action); // Add Action to the result
}

4

Return the Result

The Result object, containing all mapping information, is returned to the editor.

SBLI.DataSourceService.Parameter

An object containing information about the parent and lookup parameters configured in the builder.

Example Code

DataSourceInventory.cls

global SBLI.DataSourceService.Result execute(SBLI.DataSourceService.Parameter params) {
    SObject parentRecord = params.getParentRecord();
    List<SObject> lookupRecords = params.getLookupRecords();
    ...
}

Methods

SObject getParentRecord()

Returns the parent record. If no parent parameter is configured in the builder, the value is empty.

List getLookupRecords()

Returns the lookup records. If no lookup parameter is configured in the builder, the value is empty.

SBLI.DataSourceService.Result

An object that contains all mapping information between the DataSource and the Lookup or Line Item objects, which is returned to the editor.

Mapping information is stored in SBLI.DataSourceService.Action objects, which are then added to the SBLI.DataSourceService.Result object and returned.

Example Code

DataSourceInventory.cls

SBLI.DataSourceService.Result result = new SBLI.DataSourceService.Result();
for (String productCode : inventoryData.keySet()) {
    // Store mapping information in the SBLI.DataSourceService.Action object
    SBLI.DataSourceService.Action action = new SBLI.DataSourceService.Action();
    action.setKeyValue(productCode);
    action.putSourceToTargetField(
        inventoryData.get(productCode), // DataSource value
        'Inventory__c'                 // Field API name
    );
    result.addAction(action); // Add the Action to the Result
}
return result;

Methods

addAction(SBLI.DataSourceService.Action action)

Adds an Action object containing mapping information to the Result object.

Parameter	Type	Value
action	SBLI.DataSourceService.Action	The object containing mapping information between the Lookup/Line Item and the DataSource values.

SBLI.DataSourceService.Action

An object that stores mapping information between the Lookup or Line Item and the DataSource values.

Example Code

DataSourceInventory.cls

SBLI.DataSourceService.Result result = new SBLI.DataSourceService.Result();
// Iterate over product codes and inventory data in the DataSource
for (String productCode : inventoryData.keySet()) {
    SBLI.DataSourceService.Action action = new SBLI.DataSourceService.Action();
    // Map the product code to the Lookup/Line Item Key
    action.setKeyValue(productCode);
    
    // Map inventory data to the Inventory__c field in the Lookup/Line Item
    action.putSourceToTargetField(
        inventoryData.get(productCode), // DataSource value: inventory quantity
        'Inventory__c'                 // Field API name
    );
    result.addAction(action); // Add mapping information
}
return result; // Return the final result

Methods

setKeyValue(Object keyValue)

Sets the DataSource Key value that matches the Lookup or Line Item Key.

Parameter	Type	Value
keyValue	Object	The Key value from the DataSource.

putSourceToTargetField(Object sourceValue, String targetFieldApiName)

Assigns the DataSource value to the specified Lookup or Line Item field.

Parameter	Type	Value
sourceValue	Object	The value from the DataSource.
targetFieldApiName	String	The API name of the target field in the Lookup or Line Item object.

STEP 2: Advanced DataSource Configuration

After selecting the Apex Class, specify the fields to be passed as parameters if the class requires parent or lookup information.

Ensure the Apex Class is written before configuring the DataSource.

No.	Attribute	Description	Req.
1	Apex Class	Select the Apex Class to be used for the DataSource.	✔
2	Key Field	Specify the Key Field to map data retrieved via the DataSource to the Lookup or Line Item records. The Key Field must be a field from the Lookup object. 💁 Why use a Lookup object’s field as the Key for Line Items? Since Line Items may include unsaved records, determining a unique Key value for mapping is not feasible. Using a field from the Lookup object ensures reliable mapping.	✔
3	Parameter - Parent Fields	Add a parent object’s field as a parameter if the Apex Class implementation for the DataSource requires a field value from the parent object.
4	Parameter - Lookup Fields	Add a lookup object’s field as a parameter if the Apex Class implementation for the DataSource requires a field value from the lookup object.
5	Evaluation Event	Set the execution timing for the DataSource. On Initialization: Executes when a new Line Item is added. On Loading: Executes when the Line Item screen is loaded. Before Save: Executes before a Line Item is saved. ❗ Available only for Line Items.
6	Active	Turns the DataSource on or off. It must be active to be used.	✔