Advanced Data: Executable Apex

Leverage Apex to Pull Custom Data Into Your S-Docs Templates

In this tutorial, you will learn how to reference Salesforce data into an S-Docs visual template using a custom Apex class. By completing this process, you will connect Apex-defined data, including records outside your primary object hierarchy, directly into your templates.

Prerequisites

Before starting this tutorial, ensure you have the following:

• Salesforce Apex development experience
• An active Apex class saved in your Salesforce org that utilizes the SDOC.ApexExecutable interface.

  • Ensure the class includes a declaration configured for either an object or a list appended (e.g.: SDOC.ApexExecutableObject or SDOC.ApexExecutableList )

Helpful resources to get more familiar with Apex:

Quick Start: Apex

Build Apex Coding Skills Trailmix

Apex Basics for Admins

Apex Developer Guide: Interfaces

Step 1: Create an Apex Class

1. Create a custom Apex class in your Salesforce org that utilizes the SDOC.ApexExecutable

   1. Navigate to Setup
   2. Type Apex in the Quick Search
   3. Select Apex Classes
   4. Click New
2. Declare your Apex class structure to return either an object or a list. This declaration determines whether your data is applicable for Variables or Related Lists in the S-Docs template.

For this example, we will be creating a class for under the Objects tab, so the interface declaration will be SDOC.ApexExecutableObject

1. Define the data logic required to pull your target data, even if it resides outside the primary object hierarchy.
2. Click Save

The following is an example of a properly structured Apex Class for Visual Templates:

global with sharing class CalculateOpportunityRisk implements SDOC.ApexExecutableObject {

    global SDOC.ApexExecutableInfo getInfo() {
        return new SDOC.ApexExecutableInfo(
            'Calculate Opportunity Risk',
            'Calculates a risk score and category for an Opportunity from its amount and stage.'
        );
    }

    global List<SDOC.ApexExecutableInput> getInputs() {
        return new List<SDOC.ApexExecutableInput>{
            new SDOC.ApexExecutableInput('Opportunity Id', SDOC.ApexExecutableDataType.ID_TYPE, true),
            new SDOC.ApexExecutableInput('Base Multiplier', SDOC.ApexExecutableDataType.DOUBLE_TYPE, false),
            new SDOC.ApexExecutableInput('Include Historical Data', SDOC.ApexExecutableDataType.BOOLEAN_TYPE, true),
            new SDOC.ApexExecutableInput('Risk Profile', SDOC.ApexExecutableDataType.STRING_TYPE, false)
        };
    }

    global List<SDOC.ApexExecutableOutput> getOutputs() {
        return new List<SDOC.ApexExecutableOutput>{
            new SDOC.ApexExecutableOutput('RiskScore', 'Risk Score', SDOC.ApexExecutableDataType.INTEGER_TYPE),
            new SDOC.ApexExecutableOutput('RiskCategory', 'Risk Category', SDOC.ApexExecutableDataType.STRING_TYPE),
            new SDOC.ApexExecutableOutput('RequiresApproval', 'Requires Approval', SDOC.ApexExecutableDataType.BOOLEAN_TYPE)
        };
    }

    global Map<String, Object> execute(Map<String, Object> inputs) {
        Map<String, Object> results = new Map<String, Object>();

        Id opportunityId = (Id) inputs.get('Opportunity Id');
        if (opportunityId == null) {
            return results;
        }

        // Optional inputs are absent when the template author doesn't map them
        Double baseMultiplier = (Double) inputs.get('Base Multiplier');
        if (baseMultiplier == null) {
            baseMultiplier = 1.0;
        }
        Boolean includeHistorical = inputs.get('Include Historical Data') == true;
        String riskProfile = (String) inputs.get('Risk Profile');

        List<Opportunity> opportunities = [
            SELECT Amount, StageName
            FROM Opportunity
            WHERE Id = :opportunityId
            WITH USER_MODE
            LIMIT 1
        ];
        if (opportunities.isEmpty()) {
            return results;
        }

        Opportunity opportunity = opportunities[0];
        Integer score = 0;

        if (opportunity.Amount > 1000000) {
            score += 50;
        } else if (opportunity.Amount > 100000) {
            score += 25;
        }
        if (opportunity.StageName == 'Prospecting' || opportunity.StageName == 'Qualification') {
            score += 30;
        }
        if (includeHistorical) {
            score += 15;
        }
        if (riskProfile == 'Conservative') {
            score += 20;
        }
        score = (Integer) (score * baseMultiplier);

        results.put('RiskScore', score);
        results.put('RiskCategory', score >= 60 ? 'High' : (score >= 30 ? 'Medium' : 'Low'));
        results.put('RequiresApproval', score >= 60);

        return results;
    }
}

The Apex class example above is for demonstration purposes only and is not designed to fit any organizations unique use case.

Step 2: Accessing Apex Configuration in the Visual Template Editor

1. Navigate to the S-Docs Templates tab
2. Open the template you want to update or create a new template.
3. Launch the editor by clicking the Template Editor button.

Executable Apex is a feature only available in the Visual Template Editor. Existing templates that have been built in the classic template editor will continue to launch the classic S-Docs template editor.

1. Navigate to the Variables panel and click the Advanced Data icon .
2. Select either the Objects or Lists tab, depending on how your Apex class was declared.
3. Locate the Apex subcategory.
4. Select the Click to Add option to launch the Edit Apex configuration panel.

Step 3: Configure and Map the Apex Class Data

1. On the right side of the panel, locate the Apex Class Selection drop-down menu and select the Apex class configured in Step 1.

The Apex Class selector in the Visual Template Editor includes the Name and Description defined in the Apex class for easier navigation:

1. Enter a descriptive name in the Label field.
2. Map the fields returned by your Apex class to the appropriate template fields using the drop-down menus in the Inputs section:

1. Select a Preview Record and click Validate to ensure the Apex class is collecting the expected results and they're mapped correctly.
2. Click Add Data Source.

Using Apex Collected Data in a Template

Since this example utilizes an Apex class defined for Objects, the resulting data variables will populate in the Variables panel under a new subcategory labeled with the same name as the label that was configured in the Edit Apex panel.

Click on a variable to add it to the template body.

Alternatively, the variables will display in the inline @ mention interface directly in the template body under the Data Source Relationships category.

When defining for Lists the resulting data variables will populate in as an option for Related List Source selection.