Apex for LWC and Flow: @AuraEnabled and @InvocableMethod

Most Apex written today serves someone else: a Lightning Web Component that needs data, or a Flow that needs an action no standard element provides. Two annotations open that door – @AuraEnabled for components and @InvocableMethod for Flow – and each has a few rules that separate a working demo from a production-quality API.

An LWC controller

// CaseController.cls
public with sharing class CaseController {

    public class CaseRow {                                         // shape the data for the UI
        @AuraEnabled public Id id;
        @AuraEnabled public String subject;
        @AuraEnabled public String priority;
        @AuraEnabled public Boolean isUrgent;
    }

    @AuraEnabled(cacheable=true)                                   // read-only: usable with @wire
    public static List<CaseRow> getOpenCases(Id accountId) {
        List<CaseRow> rows = new List<CaseRow>();
        for (Case c : [SELECT Id, Subject, Priority FROM Case
                       WHERE AccountId = :accountId AND IsClosed = false
                       WITH USER_MODE ORDER BY CreatedDate DESC LIMIT 50]) {
            CaseRow r = new CaseRow();
            r.id = c.Id;
            r.subject = c.Subject;
            r.priority = c.Priority;
            r.isUrgent = c.Priority == 'High';
            rows.add(r);
        }
        return rows;
    }

    @AuraEnabled                                                   // changes data: not cacheable
    public static void closeCase(Id caseId, String resolution) {
        if (String.isBlank(resolution)) {
            AuraHandledException e = new AuraHandledException('Please describe how the case was resolved.');
            e.setMessage('Please describe how the case was resolved.');   // see "testing gotcha" below
            throw e;
        }
        try {
            update as user new Case(Id = caseId, Status = 'Closed', Description = resolution);
        } catch (DmlException e) {
            throw new AuraHandledException(e.getDmlMessage(0));
        }
    }
}

// in the component's JavaScript
import { wire } from 'lwc';
import getOpenCases from '@salesforce/apex/CaseController.getOpenCases';
import closeCase from '@salesforce/apex/CaseController.closeCase';

@wire(getOpenCases, { accountId: '$recordId' }) cases;          // cacheable → @wire

async handleClose() {
    try {
        await closeCase({ caseId: this.selectedId, resolution: this.resolution });   // imperative call
    } catch (error) {
        this.errorMessage = error.body.message;                  // the AuraHandledException text
    }
}

• Methods must be static and public or global; parameter names must match the keys the component sends.
• cacheable=true allows @wire and client caching, but the method must not change data. Refresh wired data after a save with refreshApex.
• Return wrappers (with @AuraEnabled properties) or sObjects – only what the UI needs.
• Throw AuraHandledException for messages users should see; other exceptions reach the component as a generic error.

The component side of this is covered in depth in our Lightning Web Components course and the async/await with Apex lesson.

Invocable methods for Flow

An @InvocableMethod appears in Flow Builder as an Apex Action. Flow calls it in bulk – when 200 records trigger a flow, your method receives 200 requests in one list – so the signature is always list in, list out:

// AssignTerritoryAction.cls
public with sharing class AssignTerritoryAction {

    public class Request {
        @InvocableVariable(label='Billing country' required=true)
        public String country;
        @InvocableVariable(label='Annual revenue')
        public Decimal annualRevenue;
    }

    public class Result {
        @InvocableVariable(label='Territory')
        public String territory;
        @InvocableVariable(label='Needs review')
        public Boolean needsReview;
    }

    @InvocableMethod(label='Assign Territory' description='Chooses a sales territory from country and revenue' category='Sales')
    public static List<Result> assign(List<Request> requests) {
        List<Result> results = new List<Result>();
        for (Request req : requests) {                                     // one result per request, same order
            Result r = new Result();
            String c = req.country == null ? '' : req.country.trim().toLowerCase();
            r.territory = c == 'india' ? 'APAC-IN' : (c == 'germany' || c == 'france') ? 'EMEA' : 'GLOBAL';
            r.needsReview = (req.annualRevenue ?? 0) >= 10000000;
            results.add(r);
        }
        return results;
    }
}

// IntegrationApexTest.cls
@IsTest
private class IntegrationApexTest {
    @IsTest
    static void controllerReturnsOnlyOpenCasesAsRows() {
        Account acc = new Account(Name = 'Acme');
        insert acc;
        insert new List<Case>{
            new Case(Subject = 'Login issue', Priority = 'High', Status = 'New', AccountId = acc.Id),
            new Case(Subject = 'Old question', Priority = 'Low', Status = 'Closed', AccountId = acc.Id)
        };
        List<CaseController.CaseRow> rows = CaseController.getOpenCases(acc.Id);
        Assert.areEqual(1, rows.size());
        Assert.isTrue(rows[0].isUrgent);
    }

    @IsTest
    static void closeCaseNeedsAResolution() {
        try {
            CaseController.closeCase(null, '  ');
            Assert.fail('expected an AuraHandledException');
        } catch (AuraHandledException e) {
            Assert.areEqual('Please describe how the case was resolved.', e.getMessage());
        }
    }

    @IsTest
    static void auraHandledExceptionHidesItsMessageWithoutSetMessage() {
        try {
            throw new AuraHandledException('Visible to the user');
        } catch (AuraHandledException e) {
            Assert.areEqual('Script-thrown exception', e.getMessage(), 'the testing gotcha');
        }
    }

    @IsTest
    static void invocableHandlesABatchOfRequests() {
        List<AssignTerritoryAction.Request> reqs = new List<AssignTerritoryAction.Request>();
        for (String country : new List<String>{ 'India', ' germany ', 'Brazil' }) {
            AssignTerritoryAction.Request r = new AssignTerritoryAction.Request();
            r.country = country;
            r.annualRevenue = country == 'Brazil' ? 25000000 : 500000;
            reqs.add(r);
        }
        List<AssignTerritoryAction.Result> results = AssignTerritoryAction.assign(reqs);
        Assert.areEqual('APAC-IN', results[0].territory);
        Assert.areEqual('EMEA', results[1].territory);
        Assert.areEqual('GLOBAL', results[2].territory);
        Assert.isTrue(results[2].needsReview);
    }
}

✓ IntegrationApexTest.auraHandledExceptionHidesItsMessageWithoutSetMessage
✓ IntegrationApexTest.closeCaseNeedsAResolution
✓ IntegrationApexTest.controllerReturnsOnlyOpenCasesAsRows
✓ IntegrationApexTest.invocableHandlesABatchOfRequests

Tests: 4 passed, 0 failed, 4 total

Practice

Summary