> For the complete documentation index, see [llms.txt](https://help.smallbuilder.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.smallbuilder.com/smallbuilder-lists/builder-setup-steps/datasource-setup/advanced-datasource/writing-an-apex-class.md).

# Writing an Apex Class

**To use an Apex Class for the advanced DataSource setup, you must implement the** `SBLS.DataSourceService.Fetchable` **interface.** This interface requires the implementation of the `execute` method, where you define the logic for processing data. The processed data, along with mapping information to the List, must be returned as an instance of the `SBLS.DataSourceService.Result` object.

***

### :small\_orange\_diamond: Example Code

This example demonstrates retrieving inventory quantities from an external API based on product codes and mapping them to a virtual column (`SBLS_Virtual1`) in the List.

{% hint style="warning" %}
Since the `SBLS.DataSourceService.Fetchable` interface is provided by the package, both the Apex Class and its methods must be declared as **`global`** to ensure external access.
{% endhint %}

{% code title="DataSourceInventory.cls" lineNumbers="true" fullWidth="false" %}

```java
global class DataSourceInventory implements SBLS.DataSourceService.Fetchable {
    global SBLS.DataSourceService.Result execute(SBLS.DataSourceService.Parameter params) {
        // Retrieve records from the List
        List<SObject> records = params.gets();
    
        // Fetch DataSource values (e.g., inventory data) from an external API
        Map<String, Integer> inventoryData = new Map<String, Integer>(); 
        inventoryData.put('Product001', 10);
        inventoryData.put('Product002', 20);

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

        // Map DataSource values to List records
        for (String productCode : inventoryData.keySet()) {
            SBLS.DataSourceService.Action action = new SBLS.DataSourceService.Action();
            action.setKeyValue(productCode); // Set the Key value for mapping
            action.putSourceToTargetField(
                inventoryData.get(productCode), // DataSource value: inventory
                'SBLS_Virtual1'                // Virtual column API name
            );
            result.addAction(action); // Add Action to the Result
        }
        
        return result; // Return the final Result
    }
}
```

{% endcode %}

{% stepper %}
{% step %}
**Retrieve Records from the List**

Use `params.gets()` to access the records retrieved by the List.
{% endstep %}

{% step %}
**Prepare DataSource Values**

* Simulate fetching data from an external API to retrieve inventory information.
* In the example, inventory data is mapped using `ProductCode` as the key.

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

{% endstep %}

{% step %}
**Generate the Result Object**

* Create an instance of [`SBLS.DataSourceService.Action`](#sbls.datasourceservice.action) for each mapping.
* Set the **DataSource value** to the corresponding **List field** or **virtual column** using putSourceToTargetField.
* Add each action to the [`SBLS.DataSourceService.Result`](#sbls.datasourceservice.result).

```java
// Create the Result object
SBLS.DataSourceService.Result result = new SBLS.DataSourceService.Result();

// Map DataSource values to List records
for (String productCode : inventoryData.keySet()) {
    SBLS.DataSourceService.Action action = new SBLS.DataSourceService.Action();
    action.setKeyValue(productCode); // Set the Key value for mapping
    action.putSourceToTargetField(
        inventoryData.get(productCode), // DataSource value: inventory
        'SBLS_Virtual1'                // Virtual column API name
    );
    result.addAction(action); // Add Action to the Result
}
```

{% endstep %}

{% step %}
**Return the Result Object**

Return the Result object containing the mapping information for integration with the List.
{% endstep %}
{% endstepper %}

***

### :small\_orange\_diamond: SBLS.DataSourceService.Parameter

This class provides access to the **List’s records** and fields selected during the builder configuration.

#### Example Code

<pre class="language-java"><code class="lang-java">global SBLS.DataSourceService.Result execute(SBLS.DataSourceService.Parameter params) {
<strong>    List&#x3C;SObject> records = params.gets();
</strong>    ...
}
</code></pre>

#### Method

**`List<SObject> gets()`**

Returns the records retrieved from the List. If no parameters are added during the builder setup, this will return an empty value.

***

### :small\_orange\_diamond: SBLS.DataSourceService.Result

The Result class **holds all mapping information between the DataSource and the List**. Actions added to this object define how the data is integrated.

#### Example Code

<pre class="language-java" data-title="DataSourceInventory.cls" data-line-numbers><code class="lang-java">...
<strong>SBLS.DataSourceService.Result result = new SBLS.DataSourceService.Result();
</strong>for (String productCode : inventoryData.keySet()) {
    // Create an Action object to store mapping information
    SBLS.DataSourceService.Action action = new SBLS.DataSourceService.Action();
    action.setKeyValue(productCode); // Set the Key value for mapping
    action.putSourceToTargetField(
        inventoryData.get(productCode),  // DataSource value: inventory quantity
        'SBLS_Virtual1'                  // Target field: virtual column in the List
    );
<strong>    result.addAction(action); // Add Action to the Result
</strong>}
<strong>return result;
</strong></code></pre>

#### Method

**`addAction(SBLS.DataSourceService.Action action)`**

Adds an Action object containing mapping details to the Result.

<table><thead><tr><th width="118">Parameter</th><th width="294">Type</th><th>Value</th></tr></thead><tbody><tr><td><strong>action</strong></td><td><a href="#sbls.datasourceservice.action">SBLS.DataSourceService.Action</a></td><td>An instance of the <code>SBLS.DataSourceService.Action</code> class that contains the mapping information between the List and the DataSource values.</td></tr></tbody></table>

***

### :small\_orange\_diamond: SBLS.DataSourceService.Action

The Action class **stores mapping information between the DataSource and the List**.

#### Example Code

<pre class="language-java" data-title="DataSourceInventory.cls" data-line-numbers><code class="lang-java">SBLS.DataSourceService.Result result = new SBLS.DataSourceService.Result();
// Process each product code and inventory information from the DataSource
for (String productCode : inventoryData.keySet()) {
<strong>    SBLS.DataSourceService.Action action = new SBLS.DataSourceService.Action();
</strong>    // Set the product code as the Key value to map with the List/Line Item
<strong>    action.setKeyValue(productCode);
</strong>    
    // Map inventory information to the Inventory__c field in the List/Line Item
<strong>    action.putSourceToTargetField(
</strong><strong>        inventoryData.get(productCode),    // DataSource value: inventory
</strong><strong>        'SBLS_Virtual1'                    // Virtual column API name
</strong><strong>    );
</strong><strong>    result.addAction(action); // Add mapping information
</strong>}
return result; // Return the final result
</code></pre>

#### Method

**`setKeyValue(Object keyValue)`**

Sets the Key value from the DataSource that corresponds to the List’s Key.

<table><thead><tr><th width="129">Parameter</th><th width="99">Type</th><th>Value</th></tr></thead><tbody><tr><td><strong>keyValue</strong></td><td>Object</td><td>The Key value from the DataSource for mapping.</td></tr></tbody></table>

**`putSourceToTargetField(Object sourceValue, String targetFieldApiName)`**

Maps the DataSource value to a field or virtual column in the List.

<table><thead><tr><th width="206">Parameter</th><th width="100">Type</th><th>Value</th></tr></thead><tbody><tr><td><strong>sourceValue</strong></td><td>Object</td><td>The value retrieved from the DataSource.</td></tr><tr><td><strong>targetFieldApiName</strong></td><td>String</td><td>The API name of the List’s field or virtual column.</td></tr></tbody></table>