Well, you don’t have to. Big Objects were built for exactly this scenario. In this post, we’ll look at what makes them tick and explore how to avoid the design traps that bite most developers.

What are big objects?

A big object is a specialized Salesforce object designed to store hundreds of millions, or even billions of records, without degrading query performance. Unlike custom objects, they don’t count against your org’s standard storage limits. They end in __b instead of __c, and that one character signals a fundamentally different contract with the Salesforce Platform.

With the growing conversation around Data 360, some developers assume that the Big Objects feature is on its way out. That is not the case. Big Objects continues to be the right tool for high-volume, append-heavy, write-once-query-later workloads, and it is still the only native tool that can handle that level of scale.

There are two types of big objects:

• Standard Big Objects: These are predefined by Salesforce and cannot be customized. An example is FieldHistoryArchive used by Field Audit Trail.
• Custom Big Objects: These are defined by developers through the Setup UI or the Metadata API. That’s where most of the interesting work happens.

Adopting big objects means accepting strict trade-offs. For example, you lose platform automation (no triggers or flows) and out-of-the-box UI (no standard reports, list views, or sharing rules), and frontends require custom Lightning web components (LWC). Big objects are not transactional database tables, instead they are a durable, queryable ledger. Once you adopt that framing, they become an incredibly powerful tool.

Big Objects can be used to implement advanced architectural patterns. Let’s take a look at a pattern that captures and logs your org’s platform events using a big object, for improved traceability and error handling.

Architectural pattern with big objects: Payload capture and replay

Modern Salesforce orgs act as integration hubs. Platform events stream in from Enterprise Resource Planning (ERP) systems. Outbound callouts push data to marketing platforms, and webhooks arrive from payment gateways. Platform events are retained only briefly — up to 72 hours for high-volume platform events. When things fail, payloads can disappear silently as the platform event bus moves on. The data is effectively gone.

In this pattern, you write a copy of every platform event that your org publishes to a big object before any business logic runs, so the big object becomes a durable ledger of every event that has crossed the platform event bus. A platform event Apex trigger subscribes to the event (or a platform event–triggered flow) and persists it to the big object. There’s no extra publishing step, you simply log the event that you already received. After an event is captured and processed, if anything fails, the error details are written to a lightweight custom object. This improves error visibility and lets failures be replayed automatically.

The flowchart below shows integration traffic captured to the IntegrationPayloadLog__b big object before processing, failures logged to the IntegrationError__c custom object, and a daily batch job replaying failed payloads. The two objects are linked by EventUuid__c.

Let’s take a look at how to build this flow in six steps: define each of the two objects, capture every payload, log failures, automate retries, and add visibility.

Step 1: Define the Integration Payload Log big object

A robust payload log requires a well-structured big object schema. For instance, a big object like IntegrationPayloadLog__b can capture essential data. Key fields include:

• IntegrationName__c: A label for the integration or channel (for example, ERP_Inbound) and part of the composite index
• TransactionId__c: The source system’s correlation or transaction ID, when one is available
• EventUuid__c: The platform event’s globally unique ID, linking the record back to the original event and leading the composite index
• Timestamp__c: When the payload was captured
• Direction__c: Whether the payload was Inbound or Outbound
• PayloadBody__c: The raw request or response body, stored as a Long Text Area

Because this pattern logs platform event traffic, we store the platform event’s EventUuid__c. EventUuid__c is a system-generated, globally unique identifier that Salesforce assigns to each platform event upon publishing. Storing it on your big object gives you an unbreakable link between the durable payload record and the original event on the platform event bus.

Something key in this architectural pattern is to design your composite primary index right. The composite primary index is the only entry point into your big object. Queries must filter on indexed fields as full table scans don’t work at this scale. The mistake that most developers make is designing the index around what the data looks like. Instead, design it around the question you’ll ask most often.

For instance, if you want to build a system in which the core question is, “Give me the exact payloads for these specific failed events,” then the composite index should become EventUuid__c → IntegrationName__c. Set the most highly selective identifier first (the UUID), followed by the integration name. This order can map directly to the WHERE clause in SOQL queries to retrieve specific records.

Designing the composite primary index is the most important design decision that you’ll make, and unlike almost everything else on the platform, you can’t change it after deployment.

Step 2: Define the Integration Error custom object

Next, you define a lightweight custom object — for example, IntegrationError__c — specifically for capturing platform event processing failures. To ensure that your support team has exactly what they need to troubleshoot and retry the payload, we recommend creating the following fields on this custom object:

• IntegrationName__c: Name of the integration
• EventUuid__c: The shared ID linking directly to the EventUuid__c on the big object record
• Exception_Type__c: The specific class of error (e.g., CalloutException, DmlException)
• Error_Message__c: The detailed system error message
• Stack_Trace__c: The developer stack trace for deep debugging
• Failed_Record_IDs__c: A text field capturing the specific Salesforce record IDs that failed during processing
• Status__c: A picklist (e.g., Open, Retrying, Resolved) to manage the recovery workflow
• RetryCount__c: Number of times the error is reprocessed

At first glance, creating two separate objects might seem redundant. Why not just track errors in the big object? The answer comes down to the fundamental differences between big objects and standard custom objects. Think of IntegrationPayloadLog__b as your Universal Ledger (the filing cabinet that permanently stores everything) and IntegrationError__c as your Action Queue (the daily to-do list for your support team).

Here is the breakdown of when to use what:

• IntegrationPayloadLog__b (The Ledger):
  • What it stores: Every payload, regardless of success or failure. It holds the heavy, bulky JSON/XML data.
  • Volume: Millions to billions of records.
  • Platform features: No standard UI, no list views, no declarative automation (flows/triggers). It is strictly for massive-scale storage and code-based retrieval.
• IntegrationError__c (The Action Queue):
  • What it stores: Only the failures. It is extremely lightweight and does not store the heavy payload, it only stores error metadata and a pointer (EventUuid__c) back to the big object.
  • Volume: Hundreds to thousands of records (only your active, unresolved errors).
  • Platform features: Full Salesforce Platform power. You get standard list views, reportable error trends, and flow-driven escalations.

By splitting the architecture, the custom object gives you everything that big objects lack (visibility and automation). When reprocessing is needed, your retry logic queries the custom object for open errors, uses the UUID to retrieve the massive payload from the big object, and replays it. This separation keeps your human-facing error management inside the platform’s declarative tooling while preserving Big Objects as your high-volume storage engine.

Step 3: Capture the payload (the code)

Here’s the capture step for an inbound platform event. The trigger writes each event to the big object before any downstream logic runs.

trigger OrderEventCaptureTrigger on Order_Event__e (after insert) {

    List logsToInsert = new List();

    // 1. Map each incoming platform event to a big object record
    for (Order_Event__e event : Trigger.new) {
        logsToInsert.add(new IntegrationPayloadLog__b(
            EventUuid__c       = event.EventUuid,    // Index field 1
            IntegrationName__c = 'ERP_Inbound',      // Index field 2
            Direction__c       = 'Inbound',
            Timestamp__c       = System.now(),
            PayloadBody__c     = event.Payload__c    // The raw JSON/XML message
        ));
    }

    // 2. Persist to the big object BEFORE any business logic runs.
    //    insertImmediate commits immediately, so the payload is safely
    //    stored even if processing later fails.
    if (!logsToInsert.isEmpty()) {
        Database.insertImmediate(logsToInsert);
    }

    // 3. Now run the business logic. The processor handles each event in a
    //    try/catch and writes any failures to IntegrationError__c,
    //    linked back to the stored payload by EventUuid__c.
    OrderEventProcessor.process(Trigger.new);
}

The trigger does two things in order: it captures every event to the big object, then hands the same events to OrderEventProcessor.process() (shown in the next step) to run the business logic. Because Database.insertImmediate() commits the big object record immediately — outside the normal Apex transaction, so it can’t be rolled back — the payload survives even if processing throws later. That’s the whole point of capturing before the logic runs.

When managing records across both standard custom objects and big objects, it is important to understand their different DML requirements. While standard objects rely on typical DML operations like update, Big Objects does not support the update statement at all. Instead, they require the specialized Database.insertImmediate() method. To modify an existing record in a big object ledger, you simply insert a new record with the exact same Composite Primary Key. The system treats this as an upsert, overwriting the non-indexed fields with your new values without raising a duplicate error.

Step 4: Log the errors

When processing of a platform event fails, you write the error details to IntegrationError__c. The shared EventUuid__c lets your team trace the error to the exact platform event, and you can then pull the exact payload from the big object for reprocessing.
How you detect a failure depends on where the processing runs:

• Apex: Wrap the processing logic in try/catch and create the IntegrationError__c record in the catch block
• Flow: Add a Fault path to any element that can fail, and create the error record there

In every case, store the same EventUuid__c so the error points back to the exact payload in the ledger. Here’s the Apex version, where a shared IntegrationReplayService.handle() method holds the actual processing logic:

public class OrderEventProcessor {

    // Runs AFTER the payload has been captured to the big object
    public static void process(List events) {
        List errors = new List();

        for (Order_Event__e event : events) {
            try {
                // Business logic that may fail: parsing, DML, callouts, etc.
                IntegrationReplayService.handle(event.Payload__c);
            } catch (Exception ex) {
                // Record the failure, linked to the payload by EventUuid__c
                errors.add(new IntegrationError__c(
                    IntegrationName__c = 'ERP_Inbound',
                    EventUuid__c       = event.EventUuid,
                    Exception_Type__c  = ex.getTypeName(),
                    Error_Message__c   = ex.getMessage(),
                    Stack_Trace__c     = ex.getStackTraceString(),
                    Status__c          = 'Open',
                    RetryCount__c      = 0
                ));
            }
        }

        if (!errors.isEmpty()) {
            insert errors;   // Standard DML on the custom object
        }
    }
}

Step 5: Automate error recovery and retries

To maintain data integrity, resilient systems rely on automated mechanisms to periodically query for failures and attempt reprocessing. Now that our failures are neatly tracked in IntegrationError__c, we can use Batch Apex to drive our automated retry logic.

Driving the retry process from your custom error object, rather than querying the big object directly, is highly scalable. Standard custom objects support clean Batch Apex chunking and governor limit management. Your batch job simply queries the Action Queue for open errors and only queries the massive big object ledger when a payload actually needs to be reprocessed.

Schedule PayloadRetryBatch to run once a day — say, at 2:00 a.m — using a scheduled Apex class. Each run picks up every error still marked Open with fewer than three attempts, pulls the matching payload from the ledger by EventUuid__c, and replays it. If a payload succeeds, its error is marked Resolved. If it fails again, RetryCount__c is incremented and the record stays Open, so the next day’s run retries it. After three failed attempts it’s marked PermanentFailure and skipped, so a persistently broken payload can’t loop forever.

Here is what the Batch Apex pattern looks like: 

public class PayloadRetryBatch implements Database.Batchable {

    public Database.QueryLocator start(Database.BatchableContext BC) {
        // 1. Drive the logic from the standard custom object (The Action Queue)
        return Database.getQueryLocator([
            SELECT Id, EventUuid__c, RetryCount__c
            FROM IntegrationError__c
            WHERE Status__c = 'Open'
            AND RetryCount__c < 3
        ]);
    }

    public void execute(Database.BatchableContext BC, List scope) {
        List errorsToUpdate = new List();

        // 2. Gather the single key field (EventUuid__c) to retrieve the heavy payloads
        Set eventUuids = new Set();

        for (IntegrationError__c err : scope) {
            eventUuids.add(err.EventUuid__c);
        }

        // Retrieve the payloads from the Ledger using the EventUuid__c index
        List payloads = [
            SELECT EventUuid__c, PayloadBody__c
            FROM IntegrationPayloadLog__b
            WHERE EventUuid__c IN :eventUuids
        ];

        // Map payloads by EventUuid__c for easy access
        Map<String, IntegrationPayloadLog__b> payloadMap = new Map<String, IntegrationPayloadLog__b>();
        for (IntegrationPayloadLog__b p : payloads) {
            payloadMap.put(p.EventUuid__c, p);
        }

        // 3. Attempt to reprocess each failed payload
        for (IntegrationError__c err : scope) {
            IntegrationPayloadLog__b originalPayload = payloadMap.get(err.EventUuid__c);
            if (originalPayload == null) {
                continue; // Payload not found; leave the error Open for investigation
            }

            try {
                // Re-run the SAME logic the original handler uses, with the stored payload
                IntegrationReplayService.handle(originalPayload.PayloadBody__c);
                err.Status__c = 'Resolved';
            } catch (Exception ex) {
                // Failed again — increment and let the next daily run pick it up
                err.RetryCount__c += 1;
                err.Error_Message__c = ex.getMessage();
                if (err.RetryCount__c >= 3) {
                    err.Status__c = 'PermanentFailure';
                }
            }
            errorsToUpdate.add(err);
        }


        // 4. Commit changes to both systems
        if (!errorsToUpdate.isEmpty()) {
            update errorsToUpdate;     // Standard DML for the custom object
        }
    }

    public void finish(Database.BatchableContext BC) {
        // Optional: Send notifications for any records that reached PermanentFailure
    }
}

Because big object queries rely entirely on your composite primary index to handle massive data volumes, your WHERE clauses are strictly governed. Standard SOQL only permits direct matches or range filters (=, <, >, <=, >=, and IN). By structuring the batch job to collect a consolidated list of identifiers into sets, we can fully leverage the IN operator to query our EventUuid__c index field efficiently.

It’s worth understanding how this rule scales when your index has two or more fields. You don’t have to filter on every index field in every query; you can use any leading subset of your index fields, as long as you respect the order in which they were defined. In this pattern, the composite index is EventUuid__c → IntegrationName__c. That means two valid query shapes are supported:

// Valid — filters on the first index field only
WHERE EventUuid__c IN :eventUuids

// Also valid — filters on both index fields, in order
WHERE EventUuid__c IN :eventUuids AND IntegrationName__c = 'ERP_Inbound'

// Invalid — skips EventUuid__c and jumps straight to IntegrationName__c
WHERE IntegrationName__c = 'ERP_Inbound'

The retry batch uses the first shape — filtering on EventUuid__c alone — because the UUID is precise enough to locate the exact records needed. If you ever needed to narrow a query further (for example, to isolate a specific integration channel), you could add IntegrationName__c as a second filter and the query would remain valid. What you can never do is filter on a later index field while omitting an earlier one — the platform enforces strict left-to-right ordering, and any violation returns an error at runtime.

Step 6: Ensuring system observability

For daily monitoring, use standard list views on your IntegrationError__c object. Build an LWC to add deep payload inspection and one-click replay capabilities. The LWC should list open failures from IntegrationError__c and fetch the full payload from the big object by EventUuid__c on demand, with a Retry Now button. To track operational metrics like failure rates, build reports and dashboards on IntegrationError__c. Finally, fire a proactive notification when a record reaches PermanentFailure, so your team doesn’t discover dropped payloads by accident.

The same pattern, across every domain

After you’ve built this once, you’ll start seeing the same shape everywhere. Use a big object wherever you need to write at high volume, hold data durably, and query on a predictable access pattern.

• Telecom / call detail records (CDRs): Carriers use big objects for call detail records, where billions of immutable, subscriber-keyed events need to be queryable for billing and retained for regulatory compliance
• Financial services / transaction history: Write-once records, queried by account and date range, are retained for years without nightly batch jobs copying data into standard objects
• IoT / device telemetry: High-frequency sensor readings, indexed by device ID and timestamp, are fed into CRM Analytics to surface health trends to service teams
• SaaS metered billing: Every API call and feature activation written to a durable ledger is rolled up on a schedule, with full history available if a charge is ever disputed
• Marketing engagement history: Email sends, opens, and clicks are stored at scale and queryable by campaign or subscriber, without bloating transactional objects, and are ready to feed into Data 360 for attribution modeling

In all of these cases, the index question is the same: what filter will you apply most often? Start there, and the schema design follows naturally.

Big object limits and constraints

Note, in addition to the behaviour we already described, Big Objects have the following limits to take into account: 

• Each org supports up to 100 big objects
• Field types are limited to Text, Number, DateTime, Lookup, Email, Phone, URL and Long Text Area — no picklists, formulas, or checkboxes
• Fields cannot be deleted after creation 
• Triggers, flows, and Process Builder don’t fire on big object records 

These aren’t blockers, but they make upfront planning non-negotiable.

Conclusion

Big Objects isn’t a legacy feature waiting to be replaced. It’s a precision tool for a specific class of problem, and that problem keeps getting bigger. The payload capture system above is a starting point, but the same principles apply anywhere you need platform-native, durable, high-scale data storage.

Salesforce is also working on deeper integration between Big Objects and Data 360, which will make high-volume, on-platform data an even more powerful foundation for real-time analytics and AI-driven workflows. Keep an eye on the Salesforce Product Roadmap for upcoming Big Object and Data 360 integration capabilities.

Have questions or want to share how you’re using big objects? Join the conversation in the 

Salesforce Developer Community or on Salesforce Stack Exchange.

Resources

• Implementation Guide: Big Objects
• Apex Reference: Database Class
• Trailhead: Large Data Volumes
• Developer Guide: CRM Analytics
• Developer Guide: Platform Events

About the author

Laxman Vattam is a Senior Technical Architect at Salesforce focused on AI enablement, digital transformation, and large-scale platform modernization. He has spent over a decade designing scalable architectures for regulated industries. You can follow Laxman on LinkedIn.

The post The Big Objects Playbook: Payload Capture and Replay appeared first on Salesforce Developers Blog.

Instead of letting critical project context vanish, you can leverage AI to enforce architectural rigour. By implementing a decision-scoring skill, project teams can transform their coding agents into guardrails for engineering design. In this post, you’ll learn how to build the /decide pipeline, a structured framework that moves you from broad discovery to verifiable decision record.

A skill to guide technical decisions

Salesforce Ada Agent Skills is an open source skill repository for agent skills beyond writing code. /decide is a structured pipeline that demonstrates how to use AI to drive technical decisions. Type ‘/decide managed package vs. unlocked package vs. unpackaged metadata for distributing utilities across 3 orgs’ and your coding agent runs you through discovery, options grounded in official documentation, a risk matrix you challenge based on real-world experience, and a scored recommendation written to disk as a decision record.

The output is a file: versioned, reviewable, and available to the next person who asks.

The underlying pattern of discovery, debating assessment criteria, and scoring works for any technical decision for admins, developers and architects — hence the ada acronym. I’ll be using Claude Code in the examples below, but it has been designed to be used in any agent you choose with scaffolding in GitHub for Gemini and Codex CLIs.

How the pipeline works

Each step of the pipeline further refines the scope and context of a decision. Each step’s output constrains the next step’s input, narrowing from broad research to a single verifiable number.

Key design patterns

The pipeline above is what the skill does. The patterns below are how it’s implemented and the design choices to make a skill like this reliable, adaptable and worth trusting with a technical decision. Together, they give you output that you can verify, share and build on.

The folder structure

The skill is a directory of markdown files.

salesforce-ada-agent-skills/
  ├── CLAUDE.md                            	# Global rules
  ├── .mcp.json                            	# MCP server config
  ├── .claude/
  │   └── skills/
  │       ├── learn/
  │       │   └── SKILL.md                 # Learning workflow
  │       └── decide/
  │           └── SKILL.md                 	# Pipeline steps, constraints
  ├── knowledge/
  │   ├── formats/                         	# Shared output templates
  │   │   ├── options-format.md            	# Template for solution options table
  │   │   ├── criteria-format.md           	# Template for assessment criteria
  │   │   ├── risk-matrix-format.md
  │   │   └── decision-format-*.md         	# Templates for decision record output
  │   ├── scoring/                         	# Decision score methodology
  │   └── modifiers/                       	# Composable lenses
  └── output/
      └── decisions/                       	# Generated decision records

CLAUDE.md at the repo root defines the scoring pillar weights, MCP source-selection rules, and hard constraints that apply across the decision skill. The skill file (SKILL.md) handles pipeline sequencing; CLAUDE.md handles the rules that govern every step.

SKILL.md loads when you type /decide and controls the pipeline sequence. Format files are templates that the agent copies rather than interprets, producing consistent output regardless of conversation length. The scoring methodology loads only at the final step. This is about 350 lines of rubric detail that would compete for attention during discovery if inlined earlier.

Splitting files this way means you can iterate on a format without touching pipeline logic, swap scoring dimensions without changing steps, and keep the context window lean at each stage.

You are the expert

At every transition the agent pauses and asks whether you’re happy to proceed. You can reshape the analysis at any gate: add an option, remove a criterion, or challenge a rating. The pipeline prevents a flawed assumption in step one from propagating unchallenged to the recommendation. It makes the most of your real-world experiences and helps produce a higher quality output.

Research early and broadly, then verify claims

The initial research in the options step uses a broad query, so competing approaches surface together rather than being cherry-picked individually. Each proposed option is validated against documentation before being presented, and every factual claim in the risk matrix is verified with a targeted search before a rating is assigned. This layered approach balances breadth (discover all options fairly) with depth (no ungrounded claim reaches the final score).

The skill works without any MCP (Model Context Protocol) server that can search documentation.  It falls back to web search or the agent’s training knowledge and clearly states which grounding method it’s using. But documentation quality drives decision quality, so I built salesforce-content, a custom MCP server that provides keyword and vector search across recent official documentation from the admin, developer, and architect ecosystems. Any documentation on MCP will work (the repo ships with a Context7 configuration as a zero-setup alternative), but salesforce-content is preferred because it indexes trusted Salesforce sources directly rather than relying on web search, which often misses key information when the source is hard to parse.

Separate format files for every output step

Each step has its own template file specifying the exact table structure. The agent follows a concrete template more reliably than prose instructions. Splitting them from the pipeline logic means you can iterate on a format without touching the steps.

A mechanical score the agent can self-verify

Risk ratings map to fixed confidence values (Low risk = 85, Medium risk = 55, High risk = 25), weighted across pillars (Trust 20%, Reliability 20%, Operational Excellence 20%, Resource Optimization 15%, Cost Optimization 15%, Fairness 10%), and summed up into a single decision score per option. The invariant: the highest score must be the recommendation. The agent verifies this by comparing two numbers and prompt instructions to make sure there is no judgement or reasoning applied. Fixed values remove ambiguity. Pinning each level to a single value makes the score fully deterministic from the risk matrix.

I am using optimized bands based on the direction being taken by the Well-Architected framework, but these can be changed based on your preference.

An output that can be shared

Key decisions should be documented. New team members should understand the reasons behind a technical choice and allowing the output to be persistently stored was a key design choice. For this skill, I chose an Architectural Decision Record (ADR) in markdown using the option for a minimal or verbose output.

Build your own decision-scoring skill

The skill is a transferable pattern. It can be adapted to your preferred steps, scoring mechanism, and agent.

Get started

Clone the repo, follow the instructions from the readme, and type /decide followed by your question.

I built this because feedback loops matter. You can see the reasoning decomposed into a matrix of specific, citable claims, rather than a wall of persuasive prose. With a skill like this, you make better decisions, catch assumptions faster, and leave a record of the decision that the next person can actually use.

Resources

• Docs: Anthropic skills documentation
• Docs: Anthropic skills best practices
• Docs: Salesforce Well-Architected
• Video: The Next Chapter of the Well-Architected Framework

About the author

Dave Norris is a Developer Advocate at Salesforce. He’s passionate about making technical subjects broadly accessible to a diverse audience. Dave has been with Salesforce for over a decade, has over 40 Salesforce and MuleSoft certifications, and became a Salesforce Certified Technical Architect in 2013.

The post Build a Decision-Scoring Skill for Any Agent appeared first on Salesforce Developers Blog.

This post is designed to bridge the gap between basic setup and a production-ready deployment. We will trace the end-to-end journey of an event — from your sitemap code, through the SDK’s internal transformation layer, and into Data 360’s schema, data streams, and data model objects (DMOs). By the end, you will understand not just how to dispatch events, but how they’re structured, partitioned, validated, and mapped as they evolve into actionable data.

How the Data 360 module transforms your events

When you invoke SalesforceInteractions.sendEvent() (see docs), your data undergoes a significant evolution before reaching Data 360. Between sending an event and the final destination sits the Data 360 module of the Salesforce Interactions SDK. This is a transformation layer within the SDK that converts your hierarchical interaction events into the flattened schema required by Data 360.

Key insight: A single event dispatched from your sitemap can actually trigger multiple Data 360 events under the hood.

To illustrate this, consider a standard sendEvent() call designed to capture a specific button interaction along with the user’s identity.

SalesforceInteractions.sendEvent({
    interaction: {
        eventType: 'userEngagement',
        name: 'button_click'
    },
    user: {
        attributes: {
            eventType: 'contactPointEmail',
            email: 'joe.smith@domain.com'
        }
    }
})

We designed the Data 360 module to split this into two separate events before sending them to Data 360.

// Event 1: Profile data
{
    "eventType": "contactPointEmail",
    "email": "joe.smith@domain.com",
    "category": "Profile",
    // ... auto-populated fields
}

// Event 2: Engagement data
{
    "eventType": "userEngagement",
    "interactionName": "button_click",
    "category": "Engagement",
    // ... auto-populated fields
}

The eventType defined within the interaction block determines which engagement schema — and ultimately which DMO — captures behavioral data. Conversely, the eventType specified under user.attributes dictates the destination for identity data within the profile schema. This mechanism allows a single user interaction to simultaneously refresh a customer’s engagement timeline and update their contact details, routing data to distinct segments of your data model.

The end-to-end data flow

Understanding the full pipeline makes debugging significantly easier. Here’s how data flows from your website to your data model:

Every stage of the pipeline presents unique failure modes. If your data isn’t appearing as expected, consider these common troubleshooting areas:

• Schema validation: Verify that your event payload contains all of the schema fields flagged as required, otherwise Data 360 will reject the event. Any field in your event that is not defined in the schema will be ignored within the target schema. Pay close attention to data types and ensure that you are using the exact field names.
• Data stream coverage: Confirm that your data stream is configured to include the specific event type you’re dispatching. Remember, if you introduce new schema objects after deployment, you must manually update the stream to incorporate them.
• DMO mapping: Ensure that the eventType field from your behavioral data stream is correctly mapped to the Engagement Type field on your target DMO. For a generic event type data point, the eventType field in the Browse section on the left should be used instead of the eventType field in the “All Event Data” when mapping to the Website Engagement DMO. We recommend leveraging Data Explorer to view the various eventType fields in the Behavioural Events DLO to make an informed decision on which DMO they should map to.

Setting the right level of debugging is important to not only give you full visibility over failures, but to also help troubleshoot the end-to-end data flow. You can set a numerical logging level while also specifying your own custom messages from your site’s code.

// Example: Enable debug messages
SalesforceInteractions.setLoggingLevel("debug");

// Same as above, using the numeric value
SalesforceInteractions.setLoggingLevel(4);

//Output your own custom messages
SalesforceInteractions.log.debug("here")

Standard vs. custom interaction names: Choose carefully

The Interactions SDK utilizes a suite of standard interaction names, such as View Catalog Object, Add To Cart, and Purchase. These are far more than mere labels; they serve as triggers for pre-configured transformation logic residing within the Data 360 module.

When employing a standard interaction name, the resulting eventType in the Data 360 event is automatically assigned and cannot be modified. For instance, any event containing name: View Catalog Object will invariably generate eventType: catalog during the Data 360 translation process, effectively overriding any custom eventType you might have specified within the interaction block.

// Both of these produce eventType: "catalog" in the Data 360 event
{
    interaction: {
        name: "View Catalog Object",
        catalogObject: {
            type: "Product",
            id: "product-xyz"
        }
    }
}

{
    interaction: {
        name: "View Catalog Object",
        catalogObject: {
            type: "Article",
            id: "article-abc"
        }
    }
}

This distinction is critical because all events sharing a common eventType are constrained to a single DMO mapping. If your website users are engaging with diverse entities, such as insurance policies versus knowledge articles, relying on the standard View Catalog Object interaction for both will force them into the same DMO. This overlap complicates the creation of object-specific engagement models and dilutes your data granularity.

To circumvent this, you should consider custom interaction names and event types.

// Product engagement → maps to Product Browse Engagement DMO
{
    interaction: {
        name: "View",
        eventType: "productEngagement",
        catalogObject: {
            type: "Product",
            id: "product-xyz"
        }
    }
}

// Article engagement → maps to Article Engagement DMO
{
    interaction: {
        name: "Download",
        eventType: "articleEngagement",
        catalogObject: {
            type: "Article",
            id: "article-abc"
        }
    }
}

If your implementation aligns with standard patterns, then leverage the standard schema, for example, catalog interactions, cart activity, or identity updates. This approach simplifies your architecture by utilizing out-of-the-box DMO mappings via Data Kit packages. You should only implement custom event types when your specific business logic diverges from these supported interaction models.

Key insight: We have the SDK automatically assign a pageView flag to every dispatched event. A page view event (pageView: 1) is triggered when a pageConfig matches during initial page load, driven by the isMatch logic within your sitemap’s pageTypes array. Conversely, an interaction-only event (pageView: 0 or absent) is dispatched via sendEvent() through an interaction object, typically following a user action such as a click or form submission. Mastering this distinction is critical to ensuring the integrity of your engagement analytics.

How nested event payloads translate to flat Data 360 rows

Data 360 events are flat, but the SDK payloads you send are nested. When the Data 360 module ingests an event, it walks the nested structures and flattens them into a single row of columns on the target DMO. Understanding these flattening rules is critical to getting your schema and data stream to line up.

Looking at a standard interaction first:

// Product engagement → maps to Product Browse Engagement DMO
{
    interaction: {
        name: "View Catalog Object",
        catalogObject: {
            type: "Product",
            id: "product-xyz",
            attributes: {
                name: "Product name",
                description: "Product description",
                inventory: 5,
                price: 123.45
            }
        }
    }
}

For this sample of a standard event payload sent by the SDK, the Data 360 event that lands in your Behavioural Events data stream DLO will look like this:

When using custom properties at the interaction level, these are added directly to the payload. For custom objects nested under interaction, these are flattened using lowerCamelCase.

For example:

// Custom interaction
{
    interaction: {
        name: "Special Form Click",
        customProperty: "value"
    }
}

They will land in the Behavioural Events data stream DLO like this:

For custom objects nested under interaction, these are flattened using lowerCamelCase. For example:

// Custom interaction
{
    interaction: {
        name: "Special Form Click",
        customProperties: {
            anotherCustomProperties: {
                customField: "value"
            }
        }
    }
}

These will land in the Behavioural Events data stream DLO like this:

Web schema: What must match, and what’s flexible

Your web schema is a JSON document uploaded to Data 360 that defines the allowed event structure. The Interactions SDK will silently drop any event that doesn’t conform to it. Understanding what’s strictly enforced versus what’s flexible saves hours of debugging.

The following elements are strictly bound to your schema keys:

• eventType, category, and interactionName
• Field names utilized within interaction, catalogObjects, and user.identitie
• Note that these identifiers must provide an exact match to those defined in your uploaded schema

Conversely, these elements remain flexible or free-form:

• pageConfig.name (the page type name employed during sitemap matching)
• Values populated within interaction.attribute fields
• Custom payload strings, page name identifiers, and any derived values calculated via JavaScript

Key insight: Consider schema keys as the column names in a database. While the column headers must align with your schema perfectly, the specific values you use to populate them remain highly flexible.

Critical naming conventions

• Adhere to strict lowerCamelCase for all field names (e.g., use pageUrl rather than page_url or PageUrl)
• Underscores in column or field names are unsupported and will cause data ingestion to fail
• Avoid consecutive uppercase characters (e.g., prefer urlPath over URLPath)

Three essential data streams

Upon deploying data streams via your website connector, the resulting architecture is partitioned into three distinct categories, each serving a specialized role in your data ecosystem.

1. Identity stream

Automatically generated for the identity event type, this stream captures the deviceId — a unique identifier assigned by the SDK to every anonymous visitor.

This deviceId persists within the same browser typically via Local Storage or a first-party cookie. On every subsequent visit from the same browser, the same deviceId is issued. It does not, however, persist across browsers or different domains. For example, if a user visits the website in Chrome and then Safari, or on a different device, they get a different deviceId.

To ensure proper ingestion, map this to the Individual DMO using the key relationship: deviceId → Individual Id. This mapping is how Data 360 instantiates a new Individual record for every unique website visitor. The table below shows how these fields should be mapped from the identity data stream.

2. Contact point / party identification streams

These streams manage profile-level events, including contactPointEmail, contactPointPhone, and partyIdentification. They function as the critical nexus for identity resolution, bridging the gap between an anonymous deviceId and a verified customer identity. For instance, when a user authenticates and you dispatch a partyIdentification event containing their CRM ID, this data populates the Party Identification DMO, enabling Identity Resolution rulesets to unify disparate records.

Each stream maps to a different Profile-category DMO, and each has a specific field mapping that you need to get right before Identity Resolution rulesets will fire. The table below shows generic mappings. 

The deviceId → Party mapping on the Contact Point DMOs is there because the SDK’s deviceId is what unifies the Contact Point record with the Individual DMO record (which itself has deviceId → Individual Id). They share the deviceId value as the join key. Party Identification DMO keeps deviceId as the anchor. Note the convention: deviceId goes into the Party field, and the known customer identifier (Lead ID, Contact ID, loyalty number) goes into Identification Number. The literal string “Web ID” (or similar) goes into Identification Name, so IR rulesets can target this identification type by name.

Why all three matter for Identity Resolution

Each of these streams feeds a different identity rule:

• The email and phone streams give IR fuzzy-match anchors
• The partyIdentification stream gives IR an exact-match anchor — when a user logs in or submits an authenticated form and you fire a partyIdentification event with their CRM ID for example, this is the deterministic bridge that says: “this anonymous deviceId is definitely this Lead/Contact.”

3. Behavioral events stream

This consolidated stream acts as a universal receiver for all engagement event types, including page views, product interactions, cart activity, and successful purchases. Because this stream is shared across multiple event types, the eventType field becomes the essential discriminator. It is the primary attribute used to route specific interaction models to their respective destination DMOs during the mapping phase.

Consent within the behavioral events stream

Before any meaningful tracking happens, the SDK needs a recorded consent decision for the visitor. Consent events are captured as a standard engagement event type and land in the Behavioral Events stream alongside every other engagement event.

Within that stream, consent data appears as three prefixed fields:

• consentLog.provider: The system that captured the consent decision (e.g. “Salesforce Interactions” when captured by the SDK directly)
• consentLog.purpose: What the visitor has consented to (e.g., tracking, personalization, targeting)
• consentLog.status: The decision itself (opt-in, opt-out)

If your website connector is deployed and you’re seeing no data at all in Data Explorer, check consent first. Without a recorded opt-in for the relevant purpose, the SDK will suppress downstream event tracking — which looks identical to a broken sitemap or schema. Always validate that consent is firing before you start debugging anything else.

Key configuration when deploying all data streams

• Refresh mode: You must consistently utilize Partial for web data streams. Incremental mode is unsuitable here as it clears or overwrites values not explicitly present in the event payload, which invariably leads to significant data loss.
• Data space: Designate the specific data space intended to receive the ingestion. Note that these streams can be extended to additional data spaces post-deployment without incurring redundant ingestion costs.

Common field mappings

Standard field mappings often serve as a significant bottleneck during implementation. To help you avoid common pitfalls, here is a quick reference guide to ensure that your data correctly reaches its intended destination:

From Interactions SDK event to DLO

Grasping the end-to-end flow of your website events is fundamental for both debugging and schema design. This section provides a comprehensive reference for the lifecycle of each standard event type: from sending an event, through the Interactions SDK schema validation layer, and into the data stream that ultimately routes data to its target data lake object (DLO).

Architectural mapping: Schema objects to data streams

• Each Profile schema definition instantiates its own dedicated individual data stream, adhering to CamelCase naming conventions (e.g., contactPointEmail or contactPointPhone)
• All Engagement schema definitions are consolidated into a universal Behavioral Events data stream, with fields utilizing an object-prefixed notation (e.g., catalog.attributeColor)

The following screenshot shows the architectural mapping for the Catalog interaction.

This screenshot shows the architectural mapping for the Order interaction.

This screenshot shows the architectural mapping for the Cart interaction.

This screenshot shows the architectural mapping for the Website Engagement interaction.

And finally, this screenshot shows the architectural mapping for the Identity & Contact Point interactions.

Key insight: There are significant architectural advantages to leveraging standard, out-of-the-box DMOs for your mapping strategy. For instance, when capturing purchase transactions, line items, and product data, utilizing the Sales Order, Sales Order Product, and Goods Product DMOs ensures that Salesforce Personalization can natively recognize and process your data.

The Interactions SDK automatically injects several auto-populated fields into every event payload, including category, dateTime, deviceId, eventId, eventType, and sessionId. While these must be present in every schema object, they are handled entirely by the SDK — no manual configuration within your sitemap is required. The eventType field serves as the critical nexus; it binds your sitemap event to a specific schema definition and acts as the primary discriminator for routing data from the Behavioral Events stream to the appropriate destination DMO.

Deployment models: Sitemap-driven vs. Tag Manager-driven

Determining your event dispatch strategy hinges on a fundamental architectural choice: will you manage event capture natively within the sitemap, or leverage your Tag Management System? While both models are fully supported, they operate through distinct mechanisms and should not be implemented concurrently.

Option 1: Sitemap-driven architecture

In this model, the sitemap serves as the central orchestrator for all tracking logic. You define interaction objects within your pageTypes array to capture page-load events, while utilizing global.listeners or explicit sendEvent() calls for behavioral interactions like clicks and form submissions. Because the sitemap is bundled into the CDN (Content Delivery Network) script generated by your website connector, your Tag Management System (TMS) simply injects a single <script> tag — eliminating the need for custom JavaScript within the TMS itself.

This approach is ideal for maintaining a single source of truth for tracking logic. Furthermore, it is a strict requirement if your implementation includes Salesforce Personalization, as personalization experiences rely on the full sitemap context — including page types and content zones — to render correctly.

Option 2: Tag Manager-driven architecture

Conversely, the TMS-led model utilizes a lean sitemap containing only init() and initSitemap(), shifting the responsibility for event dispatching to your TMS tags. Your TMS injects the CDN script and triggers page-level events via Page View triggers and behavioral data via Click or Form triggers. This provides greater flexibility for analytics teams who prefer working within a TMS and allows you to avoid managing JavaScript sitemaps directly within Data 360.

Dispatching events from a TMS

When dispatching events from a TMS, you must explicitly set "pageView": 1 in the payload for page-load events, or omit it for interaction-only events. To ensure a successful implementation, adhere to these critical technical requirements:

• Initialization sequence: The SalesforceInteractions.sendEvent() method is only accessible after init() has resolved and initSitemap() has been invoked. Ensure that your sendEvent calls reside within the .then() callback of init().
• Race condition prevention: When utilizing a TMS, always wrap your sendEvent calls in a safety check, such as if (SalesforceInteractions), to prevent execution errors if the SDK has not finished loading.

// Standard initialization pattern for TMS-based sendEvent calls
SalesforceInteractions.init({ ... }).then(() => {
    SalesforceInteractions.initSitemap(sitemapConfig);
    // Additional sendEvent calls from TMS are safe here
});

The TMS-led approach may suit your organization if you manage a large number of brands or complex digital properties. Rather than maintaining different JavaScript sitemaps within Data 360 for each unique site, you can have just one lean sitemap for each site, with interactions managed via your Tag Management System. This can reduce the overhead of custom JavaScript maintenance within the Data 360 platform. 

It is best practice to leverage even a lean sitemap rather than trying to bypass this and do everything manually in a TMS. The CDN script that Data Cloud generates per tenant (see example) already bundles the base SDK, the Data 360 module, and the sitemap, which can perform the initialization code above. This allows the sitemap to manage background operations like device ID persistence and consent orchestration.

In practice, this architecture allows your TMS to orchestrate event capture just as it does for any other vendor. If you have an existing “form completed” trigger that currently dispatches data to your analytics and marketing pixels, you simply append a new logic block for Data 360.

// Example: TMS fires this snippet when a form-completion event triggers
SalesforceInteractions.sendEvent({
    interaction: {
        name: "Completed Form",
        attributes: {
            type: "Home Loan",
            id: "HomeLoanProduct-1",
            income: dataLayer.loanForm.income,
            loanAmount: dataLayer.loanForm.loanAmount
        }
    },
    user: {
        attributes: {
            id: "1234"
        }
    }
})

The personalization caveat: State vs. events

A critical distinction often overlooked by implementation teams is that the sitemap performs a dual role: it dispatches events while simultaneously establishing the global page state.

When you define pageTypes within a sitemap, you are doing more than specifying event triggers. You are initializing the contextual state of the page, identifying the current page type (e.g., a “Product Detail Page”), the specific anchor item (e.g., the product SKU), and the content zones eligible for personalization. This state is the foundational telemetry that Salesforce Personalization utilizes to execute logic such as:=

• “Inject a product recommendations carousel on all PDP pages”:  This requires explicit knowledge of the current page type
• “Surface recommendations related to the item currently being viewed”: This requires an active anchor item ID

Invoking sendEvent() in isolation, whether via a TMS or native application code, successfully transmits data to the Data 360 backend, but fails to set this local page state. While your events will reach Data 360, refresh customer profiles, and align with your DMO mappings, the personalization engine will lack the necessary context to identify the user’s current location or focal item. This architectural gap makes it significantly more complex to deploy context-aware, real-time personalized experiences.

The deciding question: 

If your Interactions SDK implementation is focused exclusively on data collection (triggering behavioral events), a TMS or application-led strategy is perfectly sufficient. However, if you intend to leverage Salesforce Personalization (either now or in a future phase) to render on-page experiences, the sitemap is required to maintain page state. This means your sitemap must define pageTypes, content zones, and anchor items, even if you supplement the architecture with additional sendEvent() calls from your TMS.

Even in a pure TMS-driven data collection scenario, remember that the SDK still manages several background operations: consent orchestration, device ID persistence, and initial identity resolution. While these do not require explicit sitemap configuration, they are dependent on a properly initialized base SDK.

Lastly, never implement both approaches for the same set of interactions. If a sitemap triggers a sendEvent on page load and your TMS dispatches a parallel event for the same action, your data streams will suffer from duplication. Select a single architectural source of truth: either (a) centralize all tracking within the sitemap, or (b) utilize a lean sitemap and manage all event dispatching via your TMS.

Performance considerations

A frequent point of inquiry regarding the Interactions SDK is its potential impact on page performance. The SDK payload is approximately 100KB (minified), and its impact on page load is typically measured in mere milliseconds. By utilizing a Tag Manager to handle site-specific logic rather than loading it directly from Salesforce, the total script footprint remains highly optimized. We recommend running Lighthouse audits in Google Chrome on Interactions SDK deployments to demonstrate the negligible impact on overall performance scores.

Website connector strategy

For most standard deployments, we recommend maintaining a 1:1 relationship between your website connectors and your domains. While the SDK technically permits a single connector to service multiple sites — typically by implementing conditional sitemap branching based on window.location — this architecture introduces unnecessary complexity and operational risk into your pipeline.

When managing multiple brands or digital properties, your architectural strategy should hinge on your data governance requirements. If your goal is to enable cross-brand analytics and unified personalization, you should route these connectors into a single data space. Conversely, if your priority is strict data isolation and simplified governance, separate data spaces are the better path. Remember, you can deploy multiple connectors to feed a single data space, allowing you to maintain discrete sitemaps and schemas while still achieving a unified 360-degree view of your customer.

Building your schema iteratively

Rather than attempting to define your entire schema upfront, we recommend adopting a progressive implementation strategy to minimize operational risk. Deconstruct your web connector schema into discrete files, one for each specific event type. We recommend starting with a foundational behavioral event type, such as standard website engagement for tracking page views. Incorporating this event in your schema will mean that when you deploy the data stream and finalize the DMO mapping, you can verify that events are successfully ingested by validating the payload within Data Explorer.

We also strongly recommend an iterative approach: append the next event type and repeat the validation process. This approach allows you to validate each segment of the pipeline before introducing further architectural complexity. Furthermore, it leverages Data 360’s automated mapping engine: schema fields utilizing masterLabel values that provide an exact match to DMO field labels will be auto-mapped, significantly reducing manual configuration effort.

Conclusion

Our Interactions SDK appears deceptively simple on the surface — init(), sendEvent(), and you’re done. However, the internal transformation layer, schema validation, data stream routing, and DMO mapping that occur behind the scenes are the critical junctures where implementations either succeed or fail. Mastering this full pipeline — and being deliberate about your event types, schema keys, and stream configuration — is the difference between simply “events are firing” and ensuring that “data is powering real-time personalization.”

Some personalization examples include an abandoned cart: trigger an email or SMS journey in Marketing Cloud when an AddToCart event isn’t followed by a Purchase within a defined window. Or on-site article recommendations: use the anchor item from View Catalog Object events to render a “related articles” carousel via Salesforce Personalization.

Wrapping up, we recommend that you construct your sitemap first, then test it thoroughly while monitoring the console logs. Once you validate the events within Data Explorer, build your schema to mirror the actual data payloads you observe. By adopting this progressive implementation strategy, the architectural pieces will fall into place.

Resources

• Documentation: Salesforce Data 360 Web SDK Developer Documentation
• Integration guide: Salesforce Data 360 Web and Mobile SDK
• Documentation: Translation of SDK Events to Web Connector Schemas
• Blog post: Using Data Cloud Web SDK to Capture Engagement on Your Website

About the author

Chris Charalambous is a Distinguished AI & Data Architect for the Salesforce Data 360 & Agentforce Solutions team, helping customers design scalable solutions and better understand how Data 360 and Agentforce can impact their business. His background includes software engineering, data engineering, mobile messaging, marketing automation, and data platforms. Follow Chris on LinkedIn.

Acknowledgements: A special thank you to Sergey Agadzhanov, Matija Vrzan, Ryan Lock, and Felix Agung for their invaluable contributions and technical review of this article.

The post Understanding the Data 360 Web SDK: From Website Event to Data Model appeared first on Salesforce Developers Blog.

In this post, we’ll walk through building a complete account creation form with LWC, Apex controller, and test classes. Then we’ll explain how the skill system works under the hood, and explore advanced patterns like batch jobs, service layers, and debugging workflows.

Understanding Salesforce Skills

Salesforce Skills are specialized AI capabilities that understand Salesforce architecture, governor limits, security patterns, and deployment requirements. Think of them as expert developers embedded directly into your development workflow.

When you ask Claude Code to “Create an account creation form,” it doesn’t just generate generic code. Behind the scenes, the generating-apex skill discovers your project conventions and generates production-grade code with proper error handling and governor-safe queries. It enforces guardrails like preventing SOQL in loops and validates bulkification patterns. The skill then creates test classes with 75%+ coverage using TestDataFactory patterns. Before marking the task complete, it runs Salesforce Code Analyzer and executes your test suites automatically.

How skills work under the hood

When you make a request to Claude Code, the system follows a four-stage workflow. First, Claude analyzes your prompt and matches it to the appropriate skills. Keywords like “Lightning Web Component” activate generating-lwc-components, while “Apex class” triggers generating-apex, and “test class” activates generating-apex-test.

Once matched, each skill executes its workflow. The generating-apex skill discovers your project conventions, including naming patterns and existing classes. It chooses the correct pattern, i.e., Service, Controller, Batch, or another architecture, and reviews templates from its assets directory. The skill then generates your class with built-in guardrails that enforce sharing keywords and prevent SOQL in loops. Next, it calls the generating-apex-test skill to create comprehensive test coverage.

Throughout this process, Skills enforce guardrails automatically. They reject code with queries inside loops, force the sharing keyword on all classes, and won’t complete without generating test classes. For Lightning web components, they validate pattern formatting on both client and server sides. Every skill generates the required metadata files like .cls-meta.xml automatically.

Finally, before reporting success, Skills validate the generated code. They run sf code-analyzer to catch security violations, execute sf apex run test to verify functionality, and ensure 75%+ coverage. This means you get production-ready code, not just boilerplate.

Tutorial: Building an account creation form

Let’s build a real-world feature: a Lightning web component form that creates Account records with full validation, error handling, and test coverage.

Overview

We’ll create a complete solution with three components: a Lightning web component with Account Name and Phone fields, an Apex Controller with an @AuraEnabled method and error handling, and a test class with 75%+ coverage and bulk testing for 251+ records. The form will include inline validation, toast notifications, and will be ready for deployment to App Builder and Home pages.

Prerequisites

Before we dive in, make sure you have Claude Code installed (free for individual developers), Node.js for installing skills, and the Salesforce CLI authenticated to your org. You’ll need a Developer Edition org, sandbox, or scratch org. Run sf org login web to authenticate if you haven’t done so already.

Installing Salesforce Skills

Setting up Salesforce Skills takes just one command. Navigate to your Salesforce project directory and run:

npx skills add forcedotcom/sf-skills

This pulls the official Salesforce Skills library from GitHub.

Use the spacebar to select the skills you want. For this tutorial, select:

• generating-apex: For Apex class generation
• generating-apex-test: For Apex test class generation
• generating-lwc-components: For Lightning web component generation
• debugging-apex-logs: To debug your Apex classes

Press Enter to install. 

You can select the installation scope: 

• Project: Install in current directory (committed with you projects)
• Global:  Install in home directory (available for all your projects)

The skills are now available in your Salesforce Project under your-salesforce-project/skills-lock.json.

You can also take a look at all the skills in the skills-lock.json file to view your installed skills.

Currently, the forcedotcom/sf-skills library includes 60 + skills — and they’re growing. View the full list at the official sf-skills repository.

To install all available skills, add the --all flag

npx skills add forcedotcom/sf-skills --all

Note: Salesforce skills are NOT packaged as a npm package. We also do not own the “skills” npm package. We use it as a convenient way to install our skills from our GitHub repo.

Step 1: Start Claude Code

Launch Claude Code in your project directory.

claude

You’ll see the Claude Code interactive prompt. This is where the magic happens.

Step 2: Make your request

Type or paste the following prompt.

Create a complete Salesforce solution with the following components:

1. Lightning Web Component (LWC)
Build a form component named accountCreationForm with two input fields:
- Account Name (required)
- Phone (required, 10-15 digits)
- Include a Save button disabled until both fields are valid
- Display inline validation error messages
- Show success toast on save, error toast on failure
- Handle loading state with spinner

2. Apex Controller
- Create AccountCreationController class
- Method: @AuraEnabled(cacheable=false) saveAccount(String accountName, String phone)
- Use standard Phone field (Account has no standard Email field)
- Proper error handling with AuraHandledException
- Test class with ≥85% coverage

3. App Builder Integration
- Configure *.js-meta.xml for App Page and Home Page
- Provide deployment instructions

Constraints:
- Use imperative Apex (not @wire) since this is DML
- Follow Salesforce LWC best practices
- Standard objects and fields only

Here’s what the complete prompt for creating an Account Creation form, including all the requirements listed, looks like in the terminal. 

Step 3: Watch Skills in action

After you submit the prompt, Claude Code automatically activates the right skills: generating-lwc-components for the UI, generating-apex for the controller, and generating-apex-test for tests.

It discovers your project patterns, including existing naming conventions and architectural layers. Then it generates all required files:

• accountCreationForm.html: Lightning Web Component template
• accountCreationForm.js: Component logic with imperative Apex calls
• accountCreationForm.js-meta.xml: Metadata for App/Home page exposure
• AccountCreationController.cls: Apex controller with error handling
• AccountCreationController.cls-meta.xml: Apex metadata file
• AccountCreationControllerTest.cls: Test class with test methods
• AccountCreationControllerTest.cls-meta.xml: Test metadata file

Step 4: Review the generated code and test classes

Review the generated code and the test classes. You’ll notice that they are production-ready with the help of Salesforce Skills, and we’ve achieved 100% test coverage for the Apex Class.

Step 5: Deploy and test your solution

Since we’re using Claude, it can help us deploy and test our solution, or you can use Salesforce CLI commands.

Step 6: Add component to your org’s Home page

Navigate to Setup → Lightning App Builder and click New → Select Home Page. Choose a template like “Two Regions.” From the Custom components section, drag Account Creation Form onto the page. Click Save → Activation → Assign as Org Default.

The screenshot below shows the Lightning App Builder interface with the accountCreationForm component visible in the custom components panel and being placed in a Home Page layout.

Step 7: Test in Salesforce UI

Navigate to your Salesforce Home page and test the component. Leave Account Name empty and an error message appears. Enter an invalid phone number with nine digits and an error message appears. Enter valid data and the Save button enables.

This tutorial covered a single LWC plus Apex controller pattern, but Skills handle much more complex scenarios, including batch jobs with Database.Stateful, Service-Selector-Domain layered architectures, screen flows with decision routing, and debug log analysis.

Here are five patterns that you can build with Salesforce Skills:

1. Generate a batch job for data processing

Ask Claude to “Create a batch Apex class to archive Cases older than two years named CaseArchivalBatch. Query Cases where ClosedDate < LAST_N_YEARS:2, update Status__c to ‘Archived’, and include proper error handling and logging. Generate test class with 75%+ coverage.”

Claude activates generating-apex and generates CaseArchivalBatch.cls with Database.Stateful for error tracking, proper start/execute/finish methods, governor-safe queries with no SOQL in loops, and CaseArchivalBatchTest.cls with bulk testing for 251+ records.

2. Build a service layer class

Request “Create an AccountService class with a method to update Account billing addresses in bulk using the Service-Selector-Domain pattern. The method signature should be updateBillingAddresses(Map<Id, Address> addressByAccountId). Include proper error handling and generate test class with 90%+ coverage.”

Claude generates AccountService.cls with the with sharing keyword and bulkified DML, delegates queries to AccountSelector.cls, returns List<Database.SaveResult> for partial-success handling, and creates a test class using the TestDataFactory pattern.

3. Create a screen flow

Prompt “Create a screen flow for lead qualification named Lead_Qualification. Add screens for Company Name, Industry, and Annual Revenue. Include a decision element that routes to appropriate queues based on revenue. Assign to Enterprise Queue if revenue > $1M, else assign to SMB Queue.”

Claude activates generating-flow and generates Flow metadata following Salesforce best practices.

4. Debug Apex logs

Tell Claude “Analyze the Apex logs in debug.log to find why the batch job is hitting governor limits.”

Claude uses the debugging-apex-logs skill to parse log files for SOQL and DML statements, identify SOQL-in-loop violations, report CPU time and heap size consumption, and suggest optimizations.

Best practices for working with Skills

The more context you provide in your prompts, the better the output. Instead of “Create an Apex class,” try “Create an Apex controller for my AccountForm LWC that saves Account records with Name and Phone validation.” Include field API names, object relationships, and any specific business logic requirements.

Claude Code is conversational, so if the first pass isn’t quite right, just ask for changes. You can say “Add bulk error handling to that controller” or “Change the test class to use TestDataFactory patterns.” Skills maintain context across the conversation and update the code accordingly.

While Skills generate production-grade code, always review the output before deploying to production. Verify that field API names match your org schema, and check that custom objects and fields exist in your target org. Review security settings including sharing rules and field-level security. Test in sandbox first before production deployment, and run Salesforce Code Analyzer manually as an extra safety check.

Even if you’re an experienced developer, Skills can teach you something new. Try using them once to discover best practices that you might have missed, see how test classes should be structured with Given/When/Then patterns, and learn which Code Analyzer flags are most important for security and performance. Skills are not just automation — they’re also a teaching tool.

Expanding your Skills toolkit

Now that you’ve seen Skills in action, explore the full Skills library to see all 60+ available skills. You can build OmniStudio solutions with Flexcards and Integration Procedures, connect Data Cloud data sources, create B2B commerce stores, and generate screen flows with orchestrations.

Try advanced patterns like Trigger Frameworks using the Trigger Actions Framework (TAF), Queueable with Finalizers for async operations with cleanup logic, and Custom REST Resources to build versioned APIs with proper error handling.

Skills are open source, which means you can fork the repository and customize patterns, add your team’s naming conventions to templates, and create organization-specific skills. See the contribution guide to get started.

Finally, integrate Skills with your existing workflow. They work seamlessly with the Claude Code VS Code extension, CI/CD pipelines for generating code in automated workflows, and code review processes as a first-pass reviewer before PR submission.

Conclusion

Salesforce Skills in Claude Code transform AI from a code generator into a development expert. Instead of managing boilerplate and governor limits manually, you describe your goals and Claude implements them using production-grade patterns.

From generating Apex and LWCs to debugging logs, Skills accelerate your workflow while reinforcing best practices. This allows you to focus on solving business problems rather than repetitive implementation tasks.

Ready to get started? Download Claude Code for free and run npx skills to add forcedotcom/sf-skills in your Salesforce Project. Within minutes, you’ll be generating production-ready code from natural language prompts.

Have questions or want to share what you’ve built with Skills? Join the conversation in the Salesforce Developer Community or connect with us on LinkedIn and Twitter/X. We’d love to hear about your experience.

Resources

• Salesforce Skills Library 
• Claude Code Documentation 
• Claude Code Getting Started Guide 
• Agent Skills Specification 
• Salesforce CLI Reference 
• Trailhead: LWC Basics 
• Trailhead: Apex Testing

About the author

Akshata Sawant is a Senior Developer Advocate at Salesforce and co-author of a book titled “MuleSoft for Salesforce Developers,” published by Packt Publication. For a more in-depth look at Akshata’s accomplishments, visit her LinkedIn profile.

The post Build Production-Ready Apps in Claude Code with Salesforce Skills appeared first on Salesforce Developers Blog.

In this post, we’ll take a look at the highlights for developers across Salesforce Headless 360, Lightning Web Components (LWC), Apex, Agentforce, Data 360, and Agentforce 360 Platform developer tools.

Salesforce Headless 360

Headless 360 makes every major Salesforce capability available as an API, Model Context Protocol (MCP) tool, or CLI command — accessible to any authenticated caller, whether that’s an app, a human, or an autonomous AI agent. It’s the biggest theme of the Summer ’26 release. Headless 360 brings several innovations: hosted MCP servers, new MCP tools, coding skills, and CLI and API enhancements. Let’s dive into the primary developer features related to Headless 360 available in this release.

Salesforce Hosted MCP Servers

Salesforce Hosted MCP Servers let you connect any MCP-compatible AI client, such as Claude, ChatGPT, Cursor, or custom agents, to your Salesforce org and data through the open MCP standard. Every connection uses standard OAuth authentication, so your agents interact with Salesforce data and automation in a secure, governed way. Because Salesforce hosts them, there’s no additional infrastructure to manage. 

You get two flavors: pre-built standard servers, and custom servers that you define yourself.

Standard MCP Servers

Salesforce Hosted Standard MCP Servers are now generally available. Salesforce provides several pre-built standard hosted MCP servers, including:

• SObject Servers: SObject CRUD, SOQL queries, search
• Data 360: Data 360 queries and graph traversal
• Tableau: Analytics and visualization

Custom MCP Servers

When standard MCP servers aren’t enough, you can build custom MCP servers with granular control over which tools and prompts you expose. Custom MCP servers respect the full sharing and security model you have configured for your Salesforce org. Custom MCP tools can be built from:

• Apex Actions: Expose @InvocableMethod (see docs) annotated methods as MCP tools
• Lightning Flows: Expose autolaunched flows as MCP tools
• Apex REST: Expose custom Apex REST endpoints as MCP tools
• AuraEnabled: Expose @AuraEnabled annotated Apex methods as MCP tools
• Named Query API: Expose parameterized SOQL queries as MCP tools
• Prompt Builder: Expose prompts from Prompt Builder as MCP prompts
• Agentforce: Expose Agentforce agents as MCP tools
• API Catalog: Map Salesforce API Catalog (curated registry of REST API endpoints) to MCP tools

For a complete walkthrough, including OAuth configuration details and connecting Claude Desktop and Claude Code, read Connect Claude with Salesforce Hosted MCP Servers and Expose Custom Apex as a Hosted MCP Tool for Agents.

Developer and designer MCP servers and tools

Developers and designers get a productivity boost from MCP-powered tools that bring AI assistance directly into the IDE and coding agents.

Salesforce DX MCP server (Beta):  Two important tools land here. SLDS Guideline tools speeds up UI work with instant Salesforce Lightning Design System (SLDS) styling-hook and component-blueprint guidance. ApexGuru  brings Apex code review into your coding agent from your org’s runtime metrics.  It flags and fixes anti-patterns inline, such as SOQL or DML inside loops and redundant SOQL, and its Test Case Insights surface inefficient tests that drag down coverage.

Metadata API Context MCP Server (Beta): This server now ships five granular tools instead of one. These tools provide contextual information about Salesforce metadata types to help generate accurate metadata files, with faster responses and more efficient token usage.

Data 360 MCP Server (Developer Preview):  This open-source server connects your coding agent to Data 360. Instead of exposing roughly 200 REST operations one by one, it fronts them with three facade tools — search (find a capability by intent), payload_examples (fetch a working request body), and execute (run it) — which keep the coding agent from blowing its context window. 

Omnistudio MCP Server (Beta):  This server bridges agentic and low-code development. Use your coding agent to turn requirements — plain text, screenshots, or UX mockups — into functional Flexcard templates.

B2C DX MCP Server: Modify your Storefront Next components quickly with the Figma-to-Component tool set, converting design files directly into components.

Marketing Cloud Engagement MCP Server: Securely connect external AI agents to Marketing Cloud Engagement and expose core developer capabilities like data extensions and journeys as natural-language tools.

Agent Skills for coding agents

Agent Skills are a lightweight, open format for extending AI agent capabilities with specialized knowledge and workflows. In this release, we are open-sourcing a library of Salesforce development skills. The skills are optimized to work with the Salesforce coding agent Agentforce Vibes, and are also compatible with any other coding agent, such as Claude Code or Codex.

Skills come pre-packaged with Agentforce Vibes. For any other coding agent, install them using the npx command: npx skills add forcedotcom/sf-skills.

Salesforce CLI updates

Salesforce CLI’s 220+ commands are a core part of Salesforce Headless 360. The CLI keeps shipping every week, and recent releases shipped several updates worth knowing about. We’ll look at the highlights for developers, organized by what they help you build. The emphasis is on Agentforce DX tooling and a major credential security overhaul.

Build agents from a working starting point:

• Agent project scaffolding: Spin up a runnable Agentforce sample instead of starting from scratch. The agent template generates a Local Info Agent demonstrating Apex, Prompt Template, and Flow subagents.

sf template generate project --name my-agent --template agent

• One-command agent user: Automate the setup of service agent users, eliminating the need for manual provisioning.

sf org create agent-user --first-name Service --last-name Agent --target-org my-org

Test, preview, and debug agents:

• Agent preview is GA: You can now script interactive test sessions end to end with agent preview start, send, sessions, and end.
• Trace files for diagnosis: Inspect and manage the traces recorded during a preview session to see exactly how your agent routed and acted.

sf agent trace read --session-id  --format detail --dimension actions

• Richer evaluations (Beta): Run YAML- or JSON-defined evaluation tests for higher-quality, repeatable agent testing.

sf agent test run-eval --spec specs/my-agent-testSpec.yaml --target-org my-org

Keep credentials out of your logs:

• Secrets redacted by default: Access tokens, SFDX auth URLs, and passwords are now stripped from commands like org display and org list --json, preventing accidental leaks in continuous integration (CI) and logs.
• Deliberate secret retrieval: When you actually need a credential, ask for it explicitly.

sf org auth show-access-token --target-org my-org

As always, the deep-dive details for every command and flag live in the Salesforce CLI release notes. Read them to go further.

Salesforce Platform API updates

The platform’s APIs are a big part of Headless 360. Summer ’26 ships API version 67.0, and a few changes are worth knowing about as you build.

Plan now: SOAP login() is being retired

This is the most impactful change in this release for integration owners. SOAP login() in API versions 31.0–64.0 retires in Summer ’27. Any integration that authenticates with a username and password over SOAP will stop working. Move those integrations to OAuth — using external client apps with JWT tokens — well ahead of the cutoff. A new Any API Auth user permission lets you control who can authenticate via SOAP login(), and it’s enforced by default in newly created orgs.

Chain dependent records in one GraphQL request

GraphQL mutations can now reference any field returned by an earlier operation in the same request, not just its record ID. Use @{ref.Record.FieldName.value} for a field value, @{ref.Record.Id} (or shorthand @{ref}) for the ID. This lets you create linked records in a single round trip. Below is an example body for chaining dependent request in one GraphQL

mutation CreateChain {
  uiapi(input: { allOrNone: false }) {
    AccountCreate(input: { Account: { Name: "Headless 360 Test Co" } }) {
      Record { Id  Name { value } }
    }
    ContactCreate(input: { Contact: {
      LastName: "@{AccountCreate.Record.Name.value}"
      AccountId: "@{AccountCreate}"   # == AccountCreate.Record.Id
    }}) { Record { Id  LastName { value } } }
    OpportunityCreate(input: { Opportunity: {
      Name: "@{ContactCreate.Record.LastName.value}"
      AccountId: "@{AccountCreate.Record.Id}"
      StageName: "Value Proposition"
      CloseDate: "2026-12-31"
    }}) { Record { Id } }
  }
}

You can use a Beta Salesforce CLI command to execute any GraphQL as shown below.

sf api request graphql --body  --target-org my-org

Use JWT access tokens with SOAP API

SOAP API now accepts JWT-based access tokens from Salesforce OAuth flows in the sessionId header element, reaching parity with REST authentication and making token sharing with external services safer.

Connect REST API rate limits are relaxed

Orgs have been migrated off the restrictive per-user, per-application, per-hour Connect REST API limit and onto the more generous per-org, per-24-hour Salesforce Platform API limit — the same pool that every other API call shares. Only requests that require Chatter keep the old hourly throttle. The identical change applies to Connect in Apex.

User Interface API CSRF token

A new GET /ui-api/session/csrf resource (see docs) returns a token that you can use to protect User Interface API requests from third-party forgeries.

LWC updates

Summer ’26 is a maturity release for LWC. The big themes: cleaner architecture (state finally lives outside your components), a quicker edit-and-preview cycle (real-time previews in the browser and your IDE), better defaults (more virtualization, tighter security), and a new bridge to Agentforce. 

Here are the five features most likely to change how you build — each with the problem it solves.

• State Managers (GA): These pull data and its logic out of components into a reusable, testable layer.
• API 67.0 niceties: This includes zero-JS accordions via grouped <details>, plus faster hot reload.
• Secure downloads: LWS now blocks data: URIs, so generate files the right way.
• Dynamic lists (in Developer Preview): This renders thousands of rows smoothly with built-in virtualization.
• lightning/accApi: This new module lets your components open and drive the Agentforce panel.

State Managers for LWC

State Managers is the most consequential LWC feature going GA during this release. State managers move data and the logic that mutates it out of components into a dedicated layer. Build one as a plain JS module with the new defineState primitive from @lwc/state, which gives you three building blocks:

• atom(value): Reactive state, read through .value
• computed([deps], fn): A derived value that recomputes when a dependency changes
• setAtom(atom, value): The only way to update an atom

defineState returns a factory — each call yields a fresh, independent instance. The essential shape: one atom as the source of truth, a derived computed, and an action that mutates via setAtom.

Below is example code that demonstrates a state manager in action, handling a cart:

cartStateManager.js

import { defineState } from '@lwc/state';
export default defineState(({ atom, computed, setAtom }) => {
    const items = atom([]);                       // source of truth
    const count = computed([items], (l) => l.length); // derived
    const addItem = (item) =>                       // action
        setAtom(items, [...items.value, item]);
    return { items, count, addItem };
});

A component imports the manager module, calls the factory, then reads reactive state through .value — in JS or the template, which re-renders automatically on change. No data logic, no manual subscription:

cartSummary.js

import { LightningElement } from 'lwc';
import createCartStateManager from 'c/cartStateManager';
export default class CartSummary extends LightningElement {
    cart = createCartStateManager();
}

cartSummary.html

<template><h2>Your Cart ({cart.value.count})</h2><p>
</p></template>

For complete, runnable examples, see the open-source lwc-recipes repo. Because each instance is isolated, managers are trivially unit-testable.

Salesforce also ships built-in Lightning state managers that wrap Lightning Data Service (LDS) access to the most common UI API data and metadata — for records, object info, page layouts, and related lists (for example, lightning/stateManagerRecord and lightning/stateManagerObjectInfo). They follow the same pattern as the ones you write and participate fully in LDS caching, normalization, and subscriptions, so reach for them before rolling your own.

LWC API version 67.0: Group <details> and faster HMR

To enable the features of this release, update your bundle .js-meta.xml by setting <apiVersion>67.0</apiVersion>.

Two wins by using the 67.0 API version: hot module reloading (HMR) is faster and more memory-efficient, and you can now group native <details> elements with the name attribute for a zero-JavaScript exclusive accordion (it threw a compiler warning before 67.0). Same name = only one open at a time.

faqAccordion.html

<details key={faq.id} name="summer26-faq">
    <summary>{faq.question}</summary>
    <p>{faq.answer}</p></details>

Secure file downloads: LWS blocks data: URIs

Lightning Web Security (LWS) adds a batch of API distortions in this release. The one most likely to break code: HTMLAnchorElement.prototype.href now blocks the data: URI scheme. If you trigger client-side downloads by setting an anchor’s href to a data: URL, that stops working.

The fix is the supported pattern anyway — build a blob in JavaScript and use a blob: object URL (origin-bound, and revoked after use).

secureDownload.js

// LWS-safe: blob: URL, not data:
const blob = new Blob([this.content], { type: 'text/plain' });
const url = URL.createObjectURL(blob);
anchor.href = url;
anchor.download = this.fileName;
anchor.click();
URL.revokeObjectURL(url); // release memory

Other new distortions include Element.getAttribute, innerHTML/outerHTML getters, MutationObserver.observe, the IndexedDB factory, Promise.then/catch/finally, and more — with matching ESLint rules. Run the updated ESLint package and review the LWS Distortion Viewer before you upgrade the components to this release.

Load large lists dynamically (Developer Preview)

Rendering thousands of rows used to choke the browser, the new lightning-dynamic-list-container (see docs) and lightning-dynamic-list-item (see docs) base components use virtualization. They render only the rows in the viewport and stream the rest in as you scroll, from 50 items to 5,000.

dynamicContactList.html

<!-- Container needs a bounded height for scroll + virtualization -->
<div style="height: 400px">
  <lightning-dynamic-list-container
      list-items={allContacts}
      onrenderlistitems={handleRenderListItems}
      onloadmore={handleLoadMore}>
    <template for:each={visibleContacts} for:item="contact">
      <lightning-dynamic-list-item
          key={contact.id} item-id={contact.id}>
        <div>{contact.name}</div>
      </lightning-dynamic-list-item>
    </template>
  </lightning-dynamic-list-container>
</div>

The container fires renderlistitems as you scroll (which slice to render) and loadmore near the end:

dynamicContactList.js

handleRenderListItems(event) {
    const { listItemsToRender } = event.detail;
    this.visibleContacts = listItemsToRender;
}

You also get focus preservation and built-in accessibility (screen readers, Home/End/Arrow nav, Browse-Mode hint). 

Here are some recommendations for working with dynamic lists: keep container and item adjacent, give every item a unique item-id, and don’t set overflow: scroll on your own container — the component handles scrolling.

Talk to Agentforce from LWC with new LWC module lightning/accApi

The standout new module is lightning/accApi (see docs) — the Agentforce Conversation Client API. This headless module lets your LWC components drive the native Agentforce side panel in Lightning Experience: open it, close it, point it at a specific Employee Agent, and send natural-language utterances. Think of a “Summarize this record” button, or a context-aware launcher in a console sidebar.

The entire API is three async methods:

All three return a Promise and are queued, running in sequence. Note execute does not return the reply — the conversation renders in the panel, not your component. Import the methods and call them.

agentforceLauncher.js

import { open, close, execute } from 'lightning/accApi';

@api botId; // design-time property, set on the page

async handleOpen() {
    await open(this.botId);
}
async handleQuickAction(event) {
    const { utterance } = event.currentTarget.dataset;
    await execute(utterance, this.botId); // wrap in try/catch + toast
}

// Deploying this class at API 67.0 fails with:
//   "WITH SECURITY_ENFORCED is no longer supported, use WITH USER_MODE instead."
[SELECT Id FROM Account WITH SECURITY_ENFORCED LIMIT 1];

try {
    List a = [SELECT Id, Name, AnnualRevenue FROM Account WITH USER_MODE LIMIT 1];
} catch (QueryException e) {
    // returns Map fieldNames>
    Map<String, Set> blocked = e.getInaccessibleFields();
}

String payload = '''
{
    "Account": "${accountName}",
    "Last Updated": "${date}"
}'''.template(new Map<String, Object>{
    'accountName' => 'My Account',
    'date' => Datetime.newInstance(2018, 11, 15, 8, 0, 0)
});

@IntegrationTest
public with sharing class MyServiceIntegrationTest {
    @IntegrationTest
    public static void testServiceInteraction() {
        Account a = new Account(Name = 'Integration Test Account');
        insert as user a;
        IntegrationTest.commitTestOnly();           // data survives mid-test
        Account r = [SELECT Name FROM Account WHERE Id = :a.Id WITH USER_MODE];
        Assert.areEqual('Integration Test Account', r.Name);
    }
    @TearDown
    public static void tearDown() {
        delete as user [SELECT Id FROM Account WHERE Name = 'Integration Test Account' WITH USER_MODE];
    }
}

sf api request rest "/services/data/v67.0/einstein/data-libraries" \
  --method POST --target-org my-org \
  --body '{
    "masterLabel": "Product Docs Library",
    "developerName": "Product_Docs_Library",
    "groundingSource": { "sourceType": "SFDRIVE" }
  }'
# → { "libraryId": "1JD...", "status": "IN_PROGRESS" }

knowledge:
    rag_feature_config_id: "ARFPC_1JDcf0000024ZZ7GAM"
    citations_enabled: True

import { AgentforceService } from 'react-native-agentforce';
// Option A — Service Agent (anonymous, customer-facing)
await AgentforceService.configure({
    type: 'service',
    serviceApiURL: 'https://service.salesforce.com',
    organizationId: '00DWs00000Ip47F',
    esDeveloperName: 'Order_Support_Agent',        // the agent's API name
    serviceUISettings: { enableLightningType: true }  // render Custom Lightning Types as cards
});

// Option B — Employee Agent (internal, authenticated)
await AgentforceService.configure({
    type: 'employee',
    instanceUrl: 'https://your-domain.my.salesforce.com',
    organizationId: '00DWs00000Ip47F',
    userId: '005xx0000001234',
    agentId: '0XxWs000001DTDJK'                       // Bot Id from publishing the agent
});

await AgentforceService.setAdditionalContext({
    variables: [{ name: 'userId', type: 'Text', value: '005xx0000001234' }]
});

await AgentforceService.launchConversation();

SELECT Id, EmailOptIn__c
FROM ContactDLO__dlm
WHERE EmailOptIn__c = ''
SET OPTIONS (dataspace = 'default', honorEmptyStrings = true)

The post The Salesforce Developer’s Guide to the Summer ’26 Release appeared first on Salesforce Developers Blog.

This is the first post in a series on common anti-patterns in Lightning Web Components (LWC). In this post, you’ll learn how the three security layers in the Lightning platform work, which APIs are namespaced versus blocked, and how to avoid the most common mistakes that lead to silent failures in production. The patterns covered here apply to any custom LWC running on the Salesforce Platform.

Note: LWS distortions can change between Salesforce releases as the platform evolves. The LWS Distortion Viewer is the live source of truth for the exact behavior of every distorted API. If a pattern in this post no longer matches what you observe in your org, check the Distortion Viewer first before filing a bug.

Three security layers instead of one

Your LWC code runs inside three independent security layers. Knowing which layer does what saves you hours of debugging.

Lightning Web Security (LWS) is the namespace isolation layer. It places your component’s JavaScript in a sandboxed environment and applies distortions to browser APIs. Distortions don’t simply block APIs — they namespace storage, sanitize HTML on shared DOM elements, sandbox code evaluation, and block only a small number of APIs that could escape the sandbox. You can see every distortion and its exact behavior in the LWS Distortion Viewer.

The LWC framework enforces shadow DOM scoping, prevents access to legacy Aura globals like $A, and manages the component lifecycle.

Content Security Policy (CSP) and platform-level restrictions block inline scripts, external CDN loading, and certain URL schemes. These operate independently of LWS.

When something doesn’t work, your first question should be: which layer is responsible? Getting this wrong leads to workarounds that solve the wrong problem.

Five key anti-patterns

The patterns below fall into five categories. The first three describe how LWS distorts APIs — namespacing, sanitizing/sandboxing, and outright blocking. The fourth covers what happens at the boundary between namespaces. The fifth covers patterns that look like LWS issues, but actually come from the LWC framework or CSP. Identifying the right category is usually the fastest path to the right fix.

1. Namespaced APIs

LWS does not block these APIs — it applies a namespace isolation layer. The APIs function as expected within your own component set, but they remain blind to data established by the platform or by components residing in other namespaces.

Assuming localStorage and sessionStorage are global

LWS does not block localStorage (see docs) or sessionStorage (see docs). It namespaces them. Every key is transparently prefixed with LSKey[namespace], so each namespace gets its own isolated storage. When you call localStorage.setItem('myKey', 'value') in namespace c, Salesforce actually stores LSKey[c]myKey. Your component sees only its own keys.

This means localStorage works — but only within your namespace. If you expect to read keys set by the platform or by a component in a different namespace, you’ll get back null with no error.

// Returns null — the key was set outside this namespace's sandbox
connectedCallback() {
    const token = window.localStorage.getItem('sessionToken');
}

Use localStorage for same-namespace persistence like caching user preferences. For cross-namespace data or system-level state, use custom settings, Apex calls, or the Lightning Message Service.

Assuming document.cookie is global

Like storage, document.cookie (see docs) is namespaced by LWS, not blocked. The getter returns only cookies belonging to your sandbox, and the setter adds a sandbox prefix to new cookie keys. Platform cookies and cookies from other namespaces are invisible.

Don’t rely on document.cookie to read platform or cross-namespace cookies. Use server-side Apex to access session or authentication state instead.

2. Sanitized and sandboxed APIs

LWS does not block APIs like innerHTML (see docs), eval() (see docs), or Function() (see docs). Instead, it applies specific distortions based on the execution context. The key to avoiding silent failures is understanding exactly how the platform modifies these behaviors rather than attempting to bypass them entirely.

DOM mutation on shared elements

LWS runs in the main window, where <html>, <head>, and <body> are shared across all components. LWS protects these shared elements by sanitizing HTML strings and restricting which child elements you can add. For elements inside your component’s own shadow DOM, these APIs work normally.

Here’s the key distinction: innerHTML, outerHTML, insertAdjacentHTML, and related APIs are not blocked. They’re sanitized when targeting shared elements, and unrestricted on elements your component owns.

// innerHTML works on component-owned elements — but this is still an XSS risk
renderedCallback() {
    const container = this.template.querySelector('.container');
    container.innerHTML = `${this.userProvidedValue}`;
}

LWS will sanitize this if container is a shared element, but the real issue is the Cross Site Scripting (XSS) risk. Relying on LWS sanitization as a security mechanism is fragile — it protects shared DOM elements, not your component’s shadow DOM.

Use LWC’s declarative template directives (lwc:if, for:each, template expressions) for dynamic content. For trusted rich text from a CMS, use lightning-formatted-rich-text (see docs).

Code evaluation is sandboxed, not blocked

This one surprises many developers: eval() (see docs) and the Function() (see docs) constructor are not blocked by LWS. They run inside the sandbox — LWS ensures the evaluated code executes in the same sandboxed context as your component. Passing a string to setTimeout() (see docs) or setInterval() (see docs) works the same way.

eval('1 + 1') returns 2 in a Salesforce org. But eval() is still a bad practice. It makes code harder to analyze, blocks compiler optimizations, and creates injection vectors if the evaluated string includes user input.

// eval works in the sandbox — but don't do this
processRule(ruleString) {
    return eval(ruleString);
}

Replace dynamic code evaluation with explicit logic, a lookup table, or a strategy pattern. If you need to evaluate user-defined expressions, implement a safe parser scoped to the expression language you support.

3. APIs that are actually blocked

APIs that throw at runtime

A small number of APIs are genuinely blocked by LWS because they provide direct paths to escape the sandbox. Calling any of these throws a runtime exception.

Use LWC’s declarative template system for HTML rendering and lightning/platformResourceLoader (see docs) for script loading. There is no supported workaround for Workers inside the LWS sandbox. If your use case requires them, consider an iframe-based isolation strategy.

Network requests are not broadly restricted

fetch() (see docs), XMLHttpRequest (see docs), navigator.sendBeacon() (see docs), and fetchLater() (see docs) work normally under LWS. The only distortion blocks requests to URLs containing /aura or /webruntime — these are internal framework endpoints that your components should not access directly. All other network requests work normally, subject to standard Cross-Origin Resource Sharing (CORS) rules and your org’s CSP configuration.

// Blocked — hitting internal framework endpoints
fetch('/aura?aura.ApexAction.execute=1', { method: 'POST', body: payload });

Use Apex @AuraEnabled methods via the wire service or imperative calls instead.

4. Cross-namespace boundaries

LWS employs a proxy membrane to enforce strict isolation across namespace boundaries. Consequently, objects traversing this boundary exhibit different behaviors compared to those residing within a single namespace. For further details on the performance impacts of this membrane proxying, consult the LWS Performance documentation.

Cross-namespace object isolation

When your component receives an object from a different namespace — through an @api property, event detail, or a shared service — and you mutate that object in place, the change is not propagated back outside the sandbox. No error is thrown. The originating component just keeps seeing the original value. This is one of the hardest LWS traits to diagnose because the only symptom is stale data.

For more on the performance implications of cross-namespace membrane proxying, see the LWS Performance documentation.

// childComponent.js — namespace 'c'
@api record;

handleEdit() {
    // Mutation is silently absorbed by the LWS proxy — parent never sees it
    this.record.Name = 'Updated Name';
}

Clone the received object before modifying it, then communicate changes back with a CustomEvent.

handleEdit() {
    const updated = { ...this.record, Name: 'Updated Name' };
    this.dispatchEvent(new CustomEvent('recordchange', {
        detail: { ...updated }
    }));
}

Passing objects across namespace boundaries

Objects passed between components in different namespaces are wrapped in LWS Proxy objects (see docs). Proxy unwrapping can fail silently, giving you null or incorrect values on the receiving end. Browser extensions that listen to custom events also receive null for detail when it contains a proxied object.

// Namespace 'foo' — dispatching
this.dispatchEvent(new CustomEvent('selected', {
    detail: { record: this.selectedRecord }  // may arrive as null in another namespace
}));

Ensuring your object can be structured cloned is the key. Or, serialize the payload to JSON before dispatching and parse it on receipt. A plain string crosses the namespace boundary without proxy wrapping.

// Namespace 'foo'
this.dispatchEvent(new CustomEvent('selected', {
    detail: JSON.stringify(this.selectedRecord)
}));

// Namespace 'bar'
handleSelected(event) {
    const record = JSON.parse(event.detail);
}

5. Misattributed restrictions

These patterns fail at runtime, but the cause is not LWS. Blaming LWS leads to the wrong fix.

Referencing legacy Salesforce globals

The LWC framework (not LWS) blocks access to $A, Aura, Sfdc, and sforce in Lightning web components. These belong to the Aura framework or are deprecated platform globals. Any reference to them in LWC code fails at runtime.

This is the most common mistake when migrating Aura components to LWC.

// Pattern carried over from Aura — fails at runtime
connectedCallback() {
    const userId = $A.get('$SObjectType.CurrentUser.Id');
}

Use the LWC platform equivalents instead.

import userId from '@salesforce/user/Id';
import { getRecord } from 'lightning/uiRecordApi';
import NAME_FIELD from '@salesforce/schema/User.Name';

For a complete mapping, see the Migrate Aura Components to LWC documentation.

Loading third-party scripts from external CDNs

Loading a JavaScript library with a <script> tag pointing to an external CDN URL violates Salesforce’s CSP. The platform blocks it before LWS even comes into play. Beyond the CSP violation, external CDN loading introduces a versioning risk: the CDN may update the library at any time, silently introducing sandbox incompatibilities.

connectedCallback() {
    const script = document.createElement('script');
    script.src = 'https://cdn.example.com/somelib/v3.min.js'; // CSP violation
    document.head.appendChild(script);
}

Download the library, upload it as a Static Resource, and load it with lightning/platformResourceLoader.

import { loadScript } from 'lightning/platformResourceLoader';
import SOMELIB from '@salesforce/resourceUrl/somelib';

async renderedCallback() {
    if (this._libLoaded) return;
    this._libLoaded = true;
    await loadScript(this, SOMELIB);
    this.initializeLib();
}

Test the static-resource version in a sandbox before promoting to production. If the library requires APIs that LWS blocks (like Workers or document.write), it won’t work inside Salesforce regardless of how you load it.

Conclusion

These anti-patterns share a root cause: misunderstanding which security layer does what. LWS doesn’t block most things — it namespaces, sanitizes, and sandboxes. The APIs it actually blocks are a small, specific set. Meanwhile, the LWC framework and CSP enforce their own independent restrictions.

The mental model to remember: LWS is a namespace isolation layer, not a blanket firewall. When an API seems “blocked,” it’s usually namespaced — you’re looking at an empty namespace, not a wall. When in doubt, check the LWS Distortion Viewer for the exact behavior.

In the next post in this series, we’ll cover data and communication: the Wire Service, @api properties, and event handling. These are the three surfaces where most component-to-component bugs originate, and where a few common misunderstandings cause the most trouble.

Resources

• LWS Distortion Viewer — the definitive reference for every LWS distortion and its behavior
• Lightning Web Security architecture
• LWS Performance — performance implications of cross-namespace membrane proxying
• Lightning Web Security Developer Guide
• Migrate Aura Components to LWC

About the author

Tim Dionne is a PMTS on the Customer Centric Engineering team. He’s worked on many UI features of Salesforce over the years, starting with VisualForce, Aura Components, and Lightning Web Components with an emphasis on Lightning Web Security and Lightning Data Service.

The post Security Anti-Patterns in Lightning Web Components appeared first on Salesforce Developers Blog.

In this post, you’ll learn the basic syntax and mental model, typical use cases (including e‑commerce examples), and pilot gates and current constraints, so you can try it safely in a sandbox.

The pilot is open to any Salesforce customer — contact your Salesforce Account Executive or Customer Success Manager to request access.

Why use FORMULA() in SOQL WHERE?

When a filter depends on something that you calculate from fields, such as margin, revenue per head, days idle, or days late to ship, the usual choices are: add a formula field, maintain a duplicate rule in Apex, or query too many rows and throw away what you do not need. 

FORMULA('…') in WHERE is for the case where the rule belongs with the query: you describe the computed condition once, the platform evaluates it as part of filtering, and callers (Apex, APIs, downstream jobs) get a smaller, already qualified result set. This is especially valuable when you can not or do not want to change the data model for every subscriber org, a common scenario for ISVs or developers who want to keep operational segmentation logic visible in SOQL instead of buried in loops.

For example, say you’re working with an Order__c object and need to find every order where profit (revenue minus cost) exceeds $150. Without FORMULA(), the rule lives in Apex after a broader query; with FORMULA(), the rule moves into the WHERE clause itself.

For example, say you’re working with an Order__c object and need to find every order where profit (revenue minus cost) exceeds $150. Without FORMULA(), the rule lives in Apex after a broader query; with FORMULA(), the rule moves into the WHERE clause itself.

// Without FORMULA(): business rule lives in Apex after a wider query

 List rows = [SELECT Id, Name, Revenue__c, Cost__c FROM Order__c];
  List highMargin = new List();
  for (Order__c o : rows) {
      if (o.Revenue__c != null && o.Cost__c != null
          && (o.Revenue__c - o.Cost__c) > 150) {
          highMargin.add(o);
      }
  }

--With FORMULA(): same rule expressed in the WHERE clause 

SELECT Id, Name FROM Order__c WHERE FORMULA('Revenue__c - Cost__c') > 150

The formula expression supports addition and subtraction (+ and -). Expressions can evaluate to DOUBLE, INTEGER, DATETIME, DATE & CURRENCY.

In practice:

• INTEGER behaves like DOUBLE
• DATE behaves like DATETIME

So the rest of this post focuses on the three illustrative types: DOUBLE, DATETIME, and CURRENCY.

This pattern fits Apex and SOQL developers, ISV teams shipping logic across subscriber orgs where schema changes are hard, and anyone trying to move off the “query a large candidate set, filter in code” approach.

Beyond fitting that audience, FORMULA() in WHERE matters today because it:

• Eliminates unnecessary formula fields
• Reduces Apex complexity
• Improves performance by filtering at the query level
• Is especially valuable for ISVs who can’t modify customer schemas

Syntax: FORMULA() in WHERE

Today, FORMULA() in SOQL is available as a pilot capability: it is only supported in the WHERE clause (not HAVING).

The general shape is:

WHERE FORMULA('…') <operator> <literal>

The string is a formula expression evaluated for each row as part of filtering.

Example: E-commerce order management 

Imagine that you’re building an order analytics dashboard for a growing e-commerce platform.

Your custom Order__c object tracks:

• Revenue__c (Currency): Total order value
• Cost__c (Currency): Fulfillment cost
• OrderDate__c (Date): When customer placed order
• ShipDate__c (Date): When order shipped
• Status__c (Text): Order status

Previously, filtering orders by calculated metrics meant either:

1. Creating formula fields like Profit__c, ShippingDelay__c, ProfitMargin__c
2. Querying all orders and filtering in Apex loops

Let’s see how FORMULA() eliminates both.

The screenshot below shows a Sample Order__c records table that includes seven orders (ORD-001 through ORD-007) with Revenue, Cost, OrderDate, ShipDate, and Status columns used throughout the FORMULA() examples.

Three key use cases

For our e-commerce example, FORMULA() is particularly helpful in the following three use cases:

1. Find high-profit orders using currency arithmetic.
2. Detect late shipments using datetime arithmetic.
3. Filter by premium order criteria using combined conditions.

1. Find high-profit orders (CURRENCY arithmetic)

Our business requirement for this first use case is to identify orders with profit > $250 for priority fulfillment review.

The old way

 // Query everything, filter in memory
  List allOrders = [
      SELECT Id, Name, Revenue__c, Cost__c
      FROM Order__c
      WHERE Status__c = 'Shipped'
  ];

  List highProfitOrders = new List();
  for (Order__c order : allOrders) {
      if (order.Revenue__c != null &&
          order.Cost__c != null &&
          (order.Revenue__c - order.Cost__c) > 250) {
          highProfitOrders.add(order);
      }
  }

// Result: 3 orders (ORD-001, ORD-003, ORD-005)

The new way

SELECT Id, Name, Revenue__c, Cost__c
FROM Order__c
WHERE Status__c = 'Shipped'
AND FORMULA('Revenue__c - Cost__c') > 250

The following screenshot shows a SOQL query using the FORMULA() function to filter orders by profit: SELECT Id, Name, Revenue__c, Cost__c FROM Order__c WHERE Status__c equals “Shipped” AND FORMULA('Revenue__c - Cost__c') is greater than 250.Query results show three records: ORD-001 with 500 revenue and 200 cost, ORD-003 with 800 revenue and 300 cost, and ORD-005 with 1200 revenue and 400 cost.

2. Detect late shipments (DATETIME arithmetic)

Our business requirement here is to find orders that shipped more than three days after order date for SLA analysis. 

SELECT Id, Name, OrderDate__c, ShipDate__c
FROM Order__c
WHERE FORMULA('ShipDate__c - OrderDate__c') > 3

The screenshot below shows a SOQL query using the FORMULA() function to calculate shipping delays: SELECT Id, Name, OrderDate__c, ShipDate__c FROM Order__c WHERE FORMULA('ShipDate__c minus OrderDate__c') greater than three. Query results display two records: ORD-002 ordered April 5 and shipped April 12, and ORD-005 ordered April 15 and shipped April 25, both exceeding the three-day shipping threshold.

3. Premium order criteria (combined conditions)

Our business requirement for the third use case is to find “premium” orders: high revenue (> $600) AND fast shipping (≤ 2 days).                                                                                                           

SELECT Id, Name, Revenue__c, OrderDate__c, ShipDate__c
FROM Order__c
WHERE Revenue__c > 600
AND FORMULA('ShipDate__c - OrderDate__c') <= 2

The screenshot below shows a SOQL query combining standard field filter with the FORMULA() function: SELECT Id, Name, Revenue__c, OrderDate__c, ShipDate__c FROM Order__c WHERE Revenue__c is greater than 600 AND FORMULA('ShipDate__c minus OrderDate__c') is less than or equal to two. Query results show two records: ORD-003 with 800 revenue, ordered April 10 and shipped April 11, and ORD-007 with 650 revenue, ordered April 20 and shipped April 21, with both records meeting the high-revenue and fast-shipping criteria.

Conclusion

By applying the ideas in this post, you can express computed filters directly in SOQL. FORMULA() in WHERE turns the question from “what rows might be relevant?” into “what rows already match my computed rule?” with less schema churn. This tends to shrink Apex branching, reduce one-off formula fields for query-only rules, and make the business condition readable next to the SELECT, which helps both integrations and teams reviewing SOQL in code review and operations.

Beyond individual queries, the same pattern reinforces a broader habit: keep data access and the rule that defines “the right rows” together, so batch jobs, services, and packaged logic stay easier to maintain, especially when subscriber org schemas are not yours to reshape at will. As always, treat what you validate in a non-production org as the contract for syntax, supported types, and supported operators.

We would love your feedback on the capabilities of this pilot, and your comments will influence the GA release. Please post your questions and/or feedback on the Pilot to the Salesforce Developers Trailblazer Community. Just let us know!

Resources

• Pilot enrollment: Contact your Salesforce Account Executive or Customer Success Manager to request access to the SOQL FORMULA() pilot
• Trailhead: SOQL for Admins – Create SOQL Queries to get data from your Salesforce org

About the author

Dikshita Patel is a Software Engineer on Salesforce’s Enterprise API team, where she builds Platform APIs allowing developers, partners, and customers to query and access Salesforce data without using the Salesforce user interface. You can follow and connect with her on LinkedIn.

The post Simplify Your SOQL Queries Using SOQL FORMULA() in WHERE appeared first on Salesforce Developers Blog.

The MCE MCP Server is Salesforce’s first-party, enterprise-grade, hosted MCP server for Marketing Cloud Engagement. It’s a first step towards a truly headless experience, exposing MCE’s core marketing capabilities as tools that any MCP-compatible AI agent can call — in plain language, without writing code or navigating the UI. 

The server allows almost any external agent that supports MCP to manage data extensions, journeys, automations, and more. Note that Marketing Cloud API limits and guidelines apply (see documentation for more information).

In this post, we’ll walk you through the MCE MCP Server setup, tools, and typical use cases.

How to set up the MCE MCP Server

An agent’s permissions are a combination of the scopes in a dedicated, installed package and your own user permissions. If your installed package has access to read data extensions, but you (as a user) do not, then the MCP server does not have access. Likewise, you can limit what it can do by not granting permissions to the installed package, even if the user still has them. 

From the install package, you’ll be able to get an MCP URL that you and potentially other teammates can use. This is specific to your organization and the install package. It’s not sensitive, but it’s worth keeping in a safe place for convenience. Registering it with Claude Code, for example, is simple.

claude mcp add --transport http  https://

Other agents will be very similar. You should only need to do this once, and then authenticate from inside the agent. The details on how this works will vary depending on how the agent implements OAuth login flows, but you will be prompted to log into your Marketing Cloud account if you are not already logged in. This gives the agent a token that it can use to act on your behalf, but only for a limited time. 

For more information on MCE MCP Server setup, please see the documentation.

MCE MCP Server capabilities and tool reference

The MCE MCP Server is designed to simply wrap existing functionality provided by the Marketing Cloud Engagement APIs. For example, to get lists of data extensions, we offer a tool called sfmc_get_data_extensions. This is nearly 1:1 with a request to data/v1/customobjects on the original REST route, but made more easily discoverable for an agent. It can read the embedded documentation and discover that it needs to provide a $search variable with the search string.

As an example, this is how this tool is shown to the agent:

{
  "name": "sfmc_get_data_extensions",
  "description": "Retrieve a list of data extensions. GET /data/v1/customobjects.\n\nIMPORTANT: The $search query parameter is REQUIRED and must be a valid search term (no wildcards like * or %).\nYou must provide query_json with the structure: {\"$search\": \"term\"}\n\nExamples:\n- Search for 'customer': {\"$search\": \"customer\"}\n- Search for 'email': {\"$search\": \"email\"}\n\nSee resource 'sfmc://docs/data/v1/customobjects' for full API documentation.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query_json": {
        "type": "string",
        "description": "JSON object string containing $search parameter. REQUIRED format: {\"$search\": \"search_term\"}. The search term cannot be empty or contain wildcards (* or %)."
      }
    },
    "required": [
      "query_json"
    ]
  },
  "annotations": {
    "title": "sfmc get data extensions",
    "readOnlyHint": true,
    "destructiveHint": false,
    "idempotentHint": true,
    "openWorldHint": true
  }
}

Just as our documentation promised, the resulting tool call is simple. 

{ "$search": "test" }

The results are also pretty straightforward, even for a human to read.

Status: 200 OK
URL: https://mcfdpyw7c97kdckv65lk2j1vspd0.rest.marketingcloudapis.com/data/v1/customobjects?%24search=test

{
  "count" : 8,
  "page" : 1,
  "pageSize" : 25,
  "links" : { },
  "items" : [ {
    "id" : "bdc04e14-0209-f111-a5e8-5cba2c701e38",
    "name" : "test_7",
    "key" : "test_7",
    "description" : "Subscribers who purchased in 2018",
    "isActive" : true,
    "isSendable" : false,
    "isTestable" : false,
    "categoryId" : 1998298,
    "ownerId" : 11280369,
    "isObjectDeletable" : true,
    "isFieldAdditionAllowed" : true,
    "isFieldModificationAllowed" : true,
    "createdDate" : "2026-02-13T11:33:22.133",
    "createdById" : 11280369,
    "createdByName" : "GI Admin",
    "modifiedDate" : "2026-02-13T11:33:22.133",
    "modifiedById" : 11280369,
    "modifiedByName" : "GI Admin",
    "ownerName" : "GI Admin",
    "partnerApiObjectTypeId" : 310,
    "partnerApiObjectTypeName" : "DataExtension",
    "rowCount" : 0,
    "dataRetentionProperties" : {
      "isDeleteAtEndOfRetentionPeriod" : false,
      "isRowBasedRetention" : false,
      "isResetRetentionPeriodOnImport" : false
    },
    "fieldCount" : 15
  }, ...

It’s worth noting that the result is NOT JSON as far as the agent is concerned. It’s simply text, which in this case represents the result of making an API call to a REST endpoint. It is up to the agent to interpret this information and use it, and that’s what provides the maximum flexibility.

While the original intent of this API was to integrate with custom software, an AI agent can instead make it available interactively and with minimal friction. You don’t need to know about $search (did you forget the dollar sign?) or its syntax, the agent can deal with that. If the tool fails, it has access to the error message and relevant documentation to try again with different arguments without requiring a human to copy and paste an error code into a search engine. In this case, the tool offered sfmc://docs/data/v1/customobjects as a resource to selectively load and find out more about custom object definitions if necessary.

Another advantage is that if you are making a complex request, the AI agent (like Claude Client) can sequence tools that need to be executed in order to achieve the given functionality. For example, If you just tell the AI client to “Update the loyalty status of subscriberId 5544 to gold in XYZ DE,” the agent first gets the XYZ DE, fetches the row in DE, and updates the row without user intervention.

See the MCE MCP tool reference for more information.

What you can build with MCP + Marketing Cloud

We tested a range of use cases, from creating a new campaign journey using a single prompt to sending transactional messages in real time. AI agents are not necessarily the most creative things around, but our test agent was able to put most of the pieces we needed together, and it prompted for more context if it needed clarity on intent. Typically, you really want to hand off mundane tasks that you’d rather not deal with to an agent, such as the following.

• Create a Data Extension from a plain English description: Ask your AI agent, “Create a Data Extension for Holiday Shoppers with Email, First Name, Last Name, and Purchase Date.” The agent maps field descriptions to Marketing Cloud datatypes, sets SubscriberKey as the primary key, and returns the CustomerKey and a direct link to the new Data Extension — no Contact Builder navigation required.
• Launch a basic automated campaign without touching Journey Builder: Ask, “Create a Welcome Email journey that sends immediately when someone joins the Welcome List DE.” The agent verifies the entry source DE, builds the Entry → Email → Exit structure, resolves the email asset, and creates the journey in Draft. It then asks if you want to activate it.
• Build a nurture series conversationally: Ask, “Create a 3-email Welcome Series: send Email 1 immediately, wait 3 days, send Email 2, wait 7 days, send Email 3.” The agent parses the wait durations, names each activity descriptively, resolves all email assets, and returns the Journey Builder URL ready to review and activate.
• Add Einstein optimization to any journey step: Ask, “Add Einstein Send Time Optimization before the promotional email in my Black Friday Journey.” The agent verifies that Einstein STO is provisioned for your Business Unit, and inserts the activity immediately before the specified email.
• Propagate a new data field across every dependent DE and query in one command: Ask, “Add Propensity_Score (Number) from the Customer_Signals DE to all downstream Data Extensions and queries.” The agent traces transitive dependencies across all Query Activities and target DEs, shows you a full impact report (X DEs, Y query steps across Z automations), and — on your confirmation — adds the field to every DE, and updates every SELECT clause in dependency order. It then returns a summary of what changed and any errors encountered. This supports a dry-run mode to preview all changes before touching anything.

Having said that, we encourage you to try all your use cases with this MCP server and let us know if we are missing any crucial or nice-to-have tools on IdeaExchange.

Permissions, destructive operations, and safety guardrails

We’ve done our best to make this service as flexible and useful as possible, for as many people as possible. We decided early on to even support “destructive” operations like deleting data, even though that’s almost always a bad idea to hand off to an agent. Operations like this are annotated as destructive in a way that the agent can read, but the agent is still capable of choosing to execute them if it has the permissions to do so. It’s crucial to think through the “worst case” when assigning permissions during setup, because an agent can make mistakes. Customers are also sensitive to reputational harm if an unintentional send is triggered, so bear that in mind as well! Please make sure that you review your Installed Package scopes before using them. More details in this documentation.

Future growth

The MCE MCP Server is designed to be extended in the future, so be sure to check back often. We plan to extend coverage to other important Marketing Cloud APIs and improve what we’ve already built. Agents and the LLMs that power them are also continuously releasing and improving, so workflows that weren’t possible before might get more practical over time. 

We plan on continually improving the server and extending it to other Marketing Cloud APIs over time. Please keep an eye on our release notes, and provide feedback through your account manager or provide on IdeaExchange.

Resources

• Documentation: MCE MCP Server Setup Guide
• Documentation: MCE MCP Server Tool Reference

About the author

​​Swetha Pinninti is a Director of Engineering at Salesforce on the Marketing Cloud Einstein team. 

Patrick Frampton is a Lead Member of Technical Staff at Salesforce on the Marketing Cloud Einstein team.

The post The MCP Server for Marketing Cloud Engagement is Now GA appeared first on Salesforce Developers Blog.

This post breaks down the structure of a Salesforce agent skill using Apex as an example. For clarity, we’ll use Claude Code to highlight specific examples, but the principles apply to any agent. We’ll cover what a skill is, the project structure, and how to get started creating your first skill.

What is an agent skill?

An agent skill is a structured prompt package that transforms Claude from a general-purpose assistant into a specialist. Rather than relying on the model’s training data alone, a skill provides explicit workflow contracts, reference material, code templates, and automated validators that load into context when the skill activates.

The large language models (LLMs) that power Claude already know the programming languages across the Salesforce ecosystem: Apex, LWC, SOQL, etc. But knowing a language and consistently producing high-quality code that adheres to best practices are two different things. A skill bridges that gap.

Each skill lives in a folder with a predictable structure:

skills/authoring-apex/
├── SKILL.md              # The execution contract
├── references/           # Decision trees, patterns, guardrails
├── assets/               # Example code
└── hooks/scripts/        # Python validators

At minimum, you need a SKILL.md, which is the entry point that Claude reads when the skill activates. Everything else is scaffolding that you add as the skill grows. Start with one SKILL.md and one reference doc, and add hooks when you want mechanical enforcement rather than relying on instructions alone.

Skills activate based on frontmatter. Frontmatter is the YAML metadata block between the ‘---’ delimiters at the top of a markdown file. It’s not rendered as content, but it’s there to be read as machine-readable configuration. In a skill, the frontmatter tells an agent when to activate: the name field identifies the skill, and the description field contains the trigger rules that the agent uses to decide whether this skill is relevant to the current task.

In the example below, the description uses a TRIGGER when / DO NOT TRIGGER when structure that gives the agent both positive and negative match criteria. This eliminates the ambiguous middle ground (like “is this SOQL query part of Apex authoring or the SOQL skill?”) that causes misfires when you only tell the model what to activate on.

---
name: authoring-apex
description: >
  TRIGGER when: user writes, edits, or reviews Salesforce Apex code —
  .cls or .trigger files including service classes, selector classes,
  trigger handlers, test classes, batch jobs, queueable classes,
  invocable methods, or Apex REST endpoints.
  DO NOT TRIGGER when: user works on LWC JavaScript, Flow XML,
  standalone SOQL queries, or running existing tests.
---

This is a simplified version. In practice, the description is more comprehensive: listing every class type (schedulable, AuraEnabled, HttpCalloutMock) and naming which skill handles each excluded case (e.g. “use authoring-lwc” for LWC JavaScript). The more specific the boundary, the fewer misfires.

When a matching task is detected, Claude loads the SKILL.md and follows the workflow. You can also trigger a skill manually with /skill-name in the prompt. Either way, the full skill context — workflow, references, templates — is injected automatically. You never paste the SKILL.md content into the conversation yourself.

The skill format itself (a SKILL.md with frontmatter, references, and assets) is an open specification maintained by Anthropic under Apache 2.0 and open to community contributions. The SKILL.md, references, and templates that you write are portable. The hooks mechanism (hooks.yaml with PostToolUse lifecycle events) is Claude Code-specific — if you use another agent runtime, you’d wire validation differently, but the skill content travels with you. This makes skills headless. Use them with Agentforce Vibes, Claude Code, Cursor, VS Code, Gemini CLI, OpenAI Codex, Windsurf, Roo Code, Goose, or any of the 30+ agents that support the open specification.

The structure of an agent skill

SKILL.md: The execution contract

This is the key, non-reorderable workflow with hard exit criteria for each phase that will be followed when the skill is used. Here is a simplified example showing the structure. Your real SKILL.md would have more detail in each phase, but the shape is the same: ordered phases with exit criteria.

Follow this workflow in order. Do not skip, merge, or reorder steps.
If blocked, stop and ask for missing context. If not applicable, mark `N/A`
with a one-line justification in the report.

## Required Inputs

Gather or infer before authoring:

- Class type (service, selector, batch, queueable, invocable, trigger handler)
- Target object(s) and business goal
- Sharing default (`with sharing` unless justified)
- Trigger framework already in use (or explicit choice)

The phases:

### Phase 1 — Author
1. **Discover project conventions** — scan for existing patterns, trigger
     framework, naming style
2. **Choose the smallest correct pattern**:

  | Need               | Pattern                              |
  | ------------------ | ------------------------------------ |
  | Business logic     | Service class                        |
  | Data access        | Selector class                       |
  | Trigger logic      | Trigger handler (framework required) |
  | Flow integration   | @InvocableMethod                     |
  | Bulk processing    | Batch Apex                           |
  | Async work         | Queueable                            |

3. **Read the matching template** from `assets/` before authoring
4. **Author with guardrails** — apply every rule in the Rules section below
5. **Generate test class** — delegate to testing skill

### Phase 2 — Validate

6. **Run code analyzer** — remediate all blocking violations; re-run until clean
7. **Execute tests** — capture pass/fail and coverage percentage

### Phase 3 — Report

8. **Report** — files, design decisions, analyzer output, test results, deploy note

If a phase doesn’t apply, Claude must document it as N/A with justification. This maps directly to Anthropic’s best practice of providing “instructions as sequential steps using numbered lists when order or completeness matters.”

references/: The knowledge library

These are your reference documents that target a specific failure mode that general training handles inconsistently. Below are some best practices from Anthropic to follow since the temptation will be to include too much information.

For an authoring-apex skill let’s explore the reference files you might consider including.

This leverages what Anthropic calls providing “context and motivation behind instructions.” The references don’t just say what to do, they explain why, enabling Claude to generalize correctly to novel situations rather than pattern-matching blindly.

As an example the anti-patterns.md could look like this. This structure is designed for practices that are likely to go wrong repeatedly. Every section follows the same BAD/GOOD formula because Claude needs to recognise and avoid independent mistakes. Learn more about these anti-patterns in the documentation.

# Apex Anti-Patterns

## Table of Contents

- [SOQL in Loops](#soql-in-loops)
- 

---

## SOQL in Loops
**Anti-pattern:** Executing SOQL queries inside a `for` or `while` loop.

**Why this fails:** Salesforce enforces a hard limit of 100 SOQL queries
per synchronous transaction. Triggers fire in batches of up to 200 records,
so a single SOQL inside a loop exhausts the limit after just 100 records.

```apex
// BAD: 1 SOQL per iteration — hits 100-query limit at record 101
for (Account acc : accounts) {
    List contacts = [SELECT Id FROM Contact WHERE AccountId = :acc.Id];
}

Fix: Query once in bulk, then iterate over results.

// GOOD: 1 SOQL total
Map<Id, List> contactsByAccount = new Map<Id, List>();
for (Contact c : [SELECT Id, AccountId FROM Contact WHERE AccountId IN :accountIds]) {
    ...
}
// add other entries to align with the anti-patterns in salesforce well-architected

For speciality examples, like transaction security policies, the markdown could follow this structure and cover one specific Apex feature that breaks all the normal rules. It needs to teach Claude when the normal rules don’t apply, what to do instead, and why. There’s no BAD/GOOD pair because the “bad” code (e.g., global without sharing) is actually the correct code in this context. Note that the example in this case refers to a worked example in the assets folder.

# Transaction Security Policy (Apex condition)

## Table of Contents

- [Overview](#overview)
- [Class shape](#class-shape)
- [Sharing](#sharing)
- [Guardrails](#guardrails)
- [Example](#example)

---

## Overview

Enhanced Transaction Security policies call Apex when Condition Builder
is not enough. Implement `TxnSecurity.EventCondition` with a single
`evaluate(SObject event)` method.

## Class shape

- Declare the class **`global`** (required for Setup selection)
- Implement `TxnSecurity.EventCondition`
- Signature: `global Boolean evaluate(SObject event)`

## Sharing

These classes are **not** user-facing controllers. Use `without sharing`.
The normal `with sharing` default does NOT apply here -- applying it
will break the policy silently.

## Guardrails

- One bulk SOQL query max (no SOQL in loops -- governor limits still apply)
- Return `true` to block the transaction, `false` to allow

## Example

See assets/transaction-security-policy.cls

assets/: Few-shot by example

Anthropic highlights that one of the most reliable ways to steer Claude’s output format, tone, and structure is with implicit few-shot examples. Few-shot just means that you provide a few good examples as a template. Each template embeds the non-negotiable requirements: ApexDoc comments, bulk-safe logic, explicit sharing declarations, CRUD/FLS enforcement, and dependency injection for testability. When Claude adapts a template, it inherits these properties by construction rather than needing to recall them from training.

For Apex specifically, the world is your oyster here, but let’s explore some good use cases.

Each template isn’t just “how to write X.” It’s a pre-loaded, few-shot example with the non-negotiable requirements baked into the structure.

hooks.yaml and validator scripts: The safety net

A hook is a shell command that Claude Code runs automatically at a specific lifecycle moment. You configure them in hooks.yaml. The script is whatever that command executes, typically a Python validator that inspects the tool’s input/output and returns structured feedback.

Hooks close the feedback loop without human intervention. Claude writes something, the hook evaluates it immediately, and Claude sees the result in the same conversation turn. The correction happens in context while Claude still has the full problem loaded.

The hooks file wires the validator to the right moment. For example, a preflight check runs when the user submits a prompt.

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 ${CLAUDE_SKILL_DIR}/hooks/scripts/preflight-apex-check.py",
            "timeout": 10000
          }
        ]
      }
    ]
  }
}

Or a PostToolUse hook fires after every file write or edit.

---
name: authoring-apex
description: ...
hooks:
  PostToolUse:
    - matcher: "Write|Edit"
      hooks:
        - type: command
          command: "python3 ${CLAUDE_SKILL_DIR}/hooks/scripts/preflight-apex-check.py"
          timeout: 90000
---

Claude Code delivers the hook context as JSON on stdin. The payload shape varies by lifecycle event: PostToolUse includes the tool name, input parameters, and output; UserPromptSubmit includes the user’s prompt text.

Consider a preflight check for your development team. The SKILL.md workflow says “run Code Analyzer” in the validate phase. But what if Code Analyzer isn’t installed or is the wrong version? Without a hook, Claude attempts the command mid-workflow, gets an error, and the developer has to diagnose a missing plugin. With a hook, the check runs the moment Apex work begins.

import json, subprocess, sys

MINIMUM_VERSION = "5.5.0"

def parse_version(v):
    """Parse version string into comparable tuple."""
    return tuple(int(x) for x in v.split(".")[:3])

def main():
    hook_input = json.load(sys.stdin)
    prompt = hook_input.get("prompt", "").lower()

    # Only check when Apex work is likely
    apex_keywords = ["apex", ".cls", "class", "trigger", "service", "selector", "batch"]
    if not any(kw in prompt for kw in apex_keywords):
        sys.exit(0)

    try:
        result = subprocess.run(
            ["sf", "plugins", "--json"],
            capture_output=True, text=True, timeout=15
        )
        if result.returncode == 0:
            plugins = json.loads(result.stdout)
            for plugin in plugins:
                if plugin.get("name") == "@salesforce/plugin-code-analyzer":
                    version = plugin.get("version", "0.0.0")
                    if parse_version(version) >= parse_version(MINIMUM_VERSION):
                        sys.exit(0)
                    else:
                        print("=== Preflight Check ===")
                        print(f"  [WARNING] Code Analyzer {version} is below minimum {MINIMUM_VERSION}.")
                        print(f"  Install: sf plugins install @salesforce/plugin-code-analyzer@latest")
                        sys.exit(0)
    except (FileNotFoundError, subprocess.TimeoutExpired, json.JSONDecodeError):
        pass

    print("=== Preflight Check ===")
    print("  [WARNING] Salesforce Code Analyzer is not installed.")
    print("  The authoring-apex skill requires it for validation.")
    print("  Install: sf plugins install @salesforce/plugin-code-analyzer")
    sys.exit(0)

if __name__ == "__main__":
    main()

The developer is told up front that their toolchain is incomplete rather than discovering it mid-workflow when the validate phase fails. 

That’s what separates an instruction from a hook. The SKILL.md says “run Code Analyzer in the validate phase.” The hook proves that it can run before the workflow even starts. Instructions are aspirational; hooks are mechanical. You want both capabilities.

Why agent skills need human and mechanical validation

Skills are not a silver bullet. They dramatically narrow the probability distribution of Claude’s outputs, but they operate on a fundamentally non-deterministic system. Two things work against you:

You can’t fully specify behavior. No matter how precise your SKILL.md, real-world requirements contain novel combinations that aren’t covered by templates or references. Claude must still make judgement calls and newer models interpret prompts more literally, so slight underspecification produces inconsistent results. If your SKILL.md says “add error handling” without specifying the pattern, you’ll get different approaches each time.

Outputs are probabilistic. Even with structured prompts, role assignment, examples, and validation hooks, you’re optimizing a hit rate. You move from 60% correct to 95% correct — a massive improvement —  but the remaining 5% is why validators exist. This is why the architecture includes both preventive measures (structured prompts, references, templates) and detective measures (automated validators, scoring rubrics, blocking on errors). The skill assumes Claude will sometimes get it wrong and builds correction into the workflow rather than pretending perfection is achievable.

Getting started

Anthropic’s golden rule for prompts applies directly: “Show your prompt to a colleague with minimal context and ask them to follow it. If they’d be confused, Claude would be too.” A well-built agent skill is unambiguous to both a human reader and the model.

You don’t need to build a skill from scratch. Anthropic provides a skill-creator skill that walks you through the full process: capturing intent, writing the SKILL.md, creating test cases, running evals, and iterating until the output meets your bar. Install it and tell Claude what you want the skill to do; it handles the scaffolding, interviews you on edge cases, and generates a working draft you can refine.

If you’d prefer to work from an existing Salesforce-specific example, the Agentforce Vibes skill library includes production-ready skills for Apex, LWC, Flow, and more. Install them, use them, and look at how they’re structured; they follow similar patterns described in this post. The Agentforce Vibes skill library puts rules and rationale inline in the SKILL.md and uses complete Apex source files as templates rather than Markdown reference docs. This keeps the skill self-contained in fewer files, though it trades modularity: updating one rule means editing the main workflow file. 

The skill grows with your needs. Start with the skill-creator or an existing skill, customize what doesn’t fit your project, and build new skills only when you have a gap not covered by existing ones.

Resources

• GitHub: Salesforce’s collection of agent skills
• Trailhead: Prompt Fundamentals
• Trailhead: Prompt Engineering Techniques
• GitHub: Anthropics Skill Creator
• Documentation: Claude Code 

About the author

Dave Norris is a Developer Advocate at Salesforce. He’s passionate about making technical subjects broadly accessible to a diverse audience. Dave has been with Salesforce for over a decade, has over 40 Salesforce and MuleSoft certifications, and became a Salesforce Certified Technical Architect in 2013.

The post Build a Salesforce Agent Skill with Claude Code appeared first on Salesforce Developers Blog.

In this post, we’ll show you how to integrate Discovery Framework, an Omniscript-based digital form engine in Agentforce for Financial Services, directly into an Agentforce agent. 

By the end, you’ll have a working solution that renders structured forms inside the Agent window, replacing error-prone conversational capture with a reliable, UI-driven experience. This solution is for Salesforce Developers and architects building Agentforce experiences for the financial services industry. It requires familiarity with Apex, Lightning Web Components (LWC), and Omniscript basics.

The problem: Conversational capture falls short

In financial services, a typical transaction dispute intake process has five stages:

1. Identifying the impacted customer and account
2. Identifying the impacted transaction with enrichment for ease of identification
3. Capturing the reason for dispute and disputed amount
4. Creating a case for dispute intake
5. Capturing a dispute questionnaire

For high-volume contact center agents, Stage 5 is the hardest. Questionnaires are dynamic, changing based on payment network rules and transaction type.

A pure conversational experience creates real problems:

• Users can’t navigate backwards to update responses
• Special UI patterns (radio buttons, checkboxes) don’t translate to text
• Any AI paraphrase of a question risks capturing the wrong answer
• Questions must appear in strict order, with required/optional labels intact
• Longer questionnaires need save-and-resume support

The screen recording below shows an agent in conversational mode, asking dispute questionnaire questions one at a time.

The solution: Discovery Framework in agents

Agentforce Financial Services provides Discovery Framework, a feature that creates digital forms to collect and validate data while avoiding time-consuming, error-prone manual methods.

This framework was originally built for non-agentic, UI-driven scenarios. When you bring it into agents, you give users navigable, structured forms that address all five problems discussed above.

Key benefits:

• Navigation between questions with ability to update responses
• Proper rendering of radio buttons, checkboxes, and other form controls
• Exact question display without AI interpretation
• Correct ordering and required/optional field marking
• State persistence for incomplete forms

The framework renders a structured form directly in the agent output, with no conversational questions and no AI paraphrase risk. The screen recording below shows an agent in a Discovery Framework experience with structured form fields, radio buttons, and navigation controls embedded in the Agent interface.

Prerequisites: This experience is available only in UI-based channels — Lightning Experience, Messaging for Experience Sites, and third-party sites. It is not supported in Voice or Short Message Service (SMS) channels, where complex UI elements can’t be displayed.

Technical architecture overview

The integration uses Agentforce’s support for custom Lightning types and custom LWC components. Here’s the component architecture:

1. Discovery Framework Omniscript: The digital form definition with assessment questions
2. Custom LWC component: Wraps the Omniscript and handles data binding
3. Apex class: Executes business logic when the Agent action runs
4. Custom Lightning type: Associates the Apex output type with the LWC renderer
5. Agent action: Uses the Apex class as its reference action and the custom Lightning type as its output renderer

When an Agent action executes via a subagent, the custom Lightning type renders in the output, displaying the Discovery Framework Omniscript directly in the Agent window.

The architecture diagram below illustrates the runtime flow: a subagent triggers an agent action, which then executes Apex class business logic and renders the custom Lightning type LWC component, wrapping the Discovery Framework Omniscript in the Agent interface.

To learn more about the underlying capability, see Enhance the Agent UI with Custom LWCs and Lightning Types.

Steps to implement Discovery Framework in Agentforce

The implementation involves five steps. You start by creating a Discovery Framework Omniscript, then build the Apex classes that define the agent action’s business logic. Next, you create a Lightning web component to wrap and render the Omniscript inside the Agent window. You then configure a custom Lightning type to associate the Apex output with the LWC, and finally, you set up the agent action, which uses the Apex class as the reference action and the Lightning type as the output render. Let’s take a detailed look.

Step 1: Create a Discovery Framework Omniscript

First, we’ll need to create a series of assessment questions, then add them as steps in an Omniscript (a drag-and-drop digital form builder in Discovery Framework). See the Discovery Framework documentation for a step-by-step walkthrough.

For this example, we’ll create two sample dispute questions of type Radio Button with Yes/No responses.

Omniscript properties:

• Type: FinancialServices
• SubType: DisputeQuestionnaire
• Language: English

Important: Configure the Omniscript for a smaller viewport, so it renders correctly inside the agent window. Open the Omniscript properties panel and set the Viewport width to a maximum of 600px. Enable Responsive Mode if available. This ensures that the form fits within the agent output area without scrolling issues.

Navigation configuration:

• Enable Allow Save for Later to let users save incomplete forms
• Enable Show Progress Indicator to display form completion status
• Configure step-by-step navigation with Previous and Next buttons
• Select Hide step chart in Step Chart Options

For detailed instructions on creating Discovery Framework Omniscripts, see the Discovery Framework documentation.

To learn more, watch the video: Discovery Framework for Financial Services Cloud 

Step 2: Create Apex classes

Next, we’ll create an Apex class that captures the business logic for the agent action. In this example, the class creates a real Case record and returns the case number and ID. You’ll want to adapt the logic to your business needs.

The following Apex classes define the input, output, and business logic for the agent action. Each class plays a specific role in handling the incoming dispute request, structuring the output data, and executing the case creation logic.

Here is sample code for the Apex classes noted above.

DisputeQuestionnaireInput.cls
This class serves as the input of the agent action and contains a disputeRequest String field.
See sample code.

DisputeQuestionnaireOutput.cls
This class serves as the output of the agent action and contains a DisputeQuestionnaireCaseOutput object.
See sample code.

DisputeQuestionnaireCaseOutput.cls
This class contains the caseNumber and caseId fields as Strings.
See sample code.

DisputeQuestionnaireAction.cls
This class has the business logic that is executed by the agent to create a case and add it to a DisputeQuestionnaireCaseOutput object which is embedded inside a DisputeQuestionnaireOutput object.
See sample code.

Step 3: Create a Lightning web component

Next, we’ll create a Lightning Web Component that wraps the Discovery Framework Omniscript from Step 1. 

The displayDisputeQuestionnaire Lightning web component wraps the Discovery Framework Omniscript and renders it inside the Agent window. This component includes an HTML, a JavaScript and an XML file. The HTML defines the component structure, the JavaScript handles data binding and event subscription, and the metadata XML registers the component as an Agentforce output target.

Here is a sample code for the displayDisputeQuestionnaire Lightning web component.

displayDisputeQuestionnaire.html
This HTML component wraps the Discovery Framework Omniscript created in Step 1, using <omnistudio-omnistudio-standard-runtime-wrapper>.

<template>
   <div class="slds-card">
           <div class="slds-card">
               <div class="slds-modal__content">
                   <omnistudio-omnistudio-standard-runtime-wrapper
                           type="FinancialServices"
                           subtype="DisputeQuestionnaire"
                           language="English"
                           prefill={prefill}>
                  </omnistudio-omnistudio-standard-runtime-wrapper>
               </div>
           </div>
   </div>
</template>

Note: We’ll use the same Type, SubType, and Language values in the HTML as configured in Step 1, as shown in above code snippet.

See sample code.

displayDisputeQuestionnaire.js
This is the JavaScript for the LWC, supporting the above HTML.

import { LightningElement, api, track } from 'lwc';
import { NavigationMixin } from 'lightning/navigation';
import pubsub from 'omnistudio/pubsub';

export default class DisplayDisputeQuestionnaire extends NavigationMixin(LightningElement) {
   _value;
   @api
   get value() {
       return this._value;
   }
   set value(value) {
       this._value = value;
   }
   @track prefill; assessmentId; caseNumber; caseId;
   connectedCallback() {
       this.caseNumber = this.value?.caseOutput?.caseNumber || null;
       this.caseId = this.value?.caseOutput?.caseId || null;
       pubsub.register('omniscript_action', {
           data: this.handleOmniAction.bind(this),
       });
   }
   handleOmniAction(data) {
       this.assessmentId = data?.assessmentId || null;
   }
}

See sample code.

displayDisputeQuestionnaire.js-meta.xml
This is the js-meta.xml for the LWC, which captures the target as AgentforceOutput.
See sample code.    

Key implementation details:

• The component subscribes to omniscript_action events to capture form completion
• The prefill property allows pre-populating form fields with contextual data
• The value property receives output from the Apex class
• Navigation handles redirecting users to the created Case record after completion
• The lightning__AgentforceOutput target in the metadata XML is required for the component to render in Agentforce

Step 4: Create a custom Lightning type

Next, we’ll create a custom Lightning type to associate the Apex output types from Step 2 with the LWC from Step 3.

The displayQuestionnaireResponse Lightning type defines the custom Lightning type. This Lightning type includes the JSON files, which tells Agentforce how to map your Apex output to the LWC renderer and validates the data structure at runtime.

Here is a sample code for the displayQuestionnaireResponse Lightning type.

renderer.json
Therenderer.json file maps the root output ($) to your LWC component.
See sample code.

schema.json
The schema.json file defines the data type structure matching your Apex output class.
See sample code.

For detailed setup instructions, see Enhance the Agent UI with Custom LWCs and Lightning Types.

Step 5: Create an agent action

Finally, we’ll create an agent action that uses the Apex classes from Step 2 for execution and the custom Lightning type from Step 4 for output rendering.

Agent action configuration steps:

1. Navigate to Setup > Agentforce > Agent Actions
2. Click New Agent Action
3. Set Reference Action Type to Apex
4. Select DisputeQuestionnaireAction as the Apex class
5. Set Output Rendering to the DisputeQuestionnaireResponse custom Lightning type
6. Configure input parameters to match the Agent Topic context
7. Add instructions for when the agent should invoke this action

Example subagent instruction:

When a customer wants to dispute a transaction, execute the Process Dispute Request action to capture detailed dispute information through a structured questionnaire. When this agent action fires as part of a subagent, the Discovery Framework Omniscript renders directly in the Agent window.

The screenshot below shows a sample agent action configuration in Agent Builder, with the disputeQuestionnaireResponse Lightning type created in Step 4 set as the output renderer.

Rendering the Discovery Framework Omniscript in an Agent Script action

If your Agent is built using Agent Script, you can also render the Discovery Framework Omniscript in an action which is part of the Agent Script. 

For the dispute example, the code snippet below would help to render the output of the action using the Discovery Framework Omniscript.

outputs:
    caseOutput: object
        label: "Case Output"
        description: "The dispute case details including case number and case Id"
        complex_data_type_name: "c__DisputeQuestionnaireResponse"
        developer_name: "caseOutput"
        is_displayable: True
        filter_from_agent: False

Testing the integration

The following are steps to test the complete integration.

1. Create a subagent that invokes your new agent action
2. Start a conversation with the agent
3. Trigger the dispute intake flow
4. Verify that the Discovery Framework form renders in the Agent interface
5. Complete the questionnaire and verify that data is captured correctly
6. Confirm that the Case record is created with the captured information

Troubleshooting tips:

• If the form doesn’t render, verify that the Omniscript Type, SubType, and Language match exactly in both the Omniscript definition and LWC component
• If data doesn’t pass correctly, check that @AuraEnabled annotations are present on all Apex output class properties
• If navigation fails, ensure that the LWC component’s js-meta.xml includes the lightning__AgentforceOutput target

Extending this pattern

This mechanism isn’t limited to Discovery Framework Omniscripts; you can apply it to any Omniscript in your org, as long as the user experience fits within a compact viewport.

Additional use cases:

• Loan application intake: Multi-step loan applications with document upload
• Insurance claims processing: Complex claim forms with conditional logic
• Customer onboarding: Know Your Customer (KYC) questionnaires with validation rules
• Financial planning: Goal-setting forms with calculation logic

The key requirement: design Omniscripts for responsive display within the agent interface viewport constraints.

Conclusion

With these five steps, you can replace fragile conversational question-and-answer flows with a reliable, structured form experience — directly inside Agentforce. This approach combines the conversational intelligence of Agentforce with the rich data collection capabilities of Discovery Framework, delivering the best of both worlds.

By following this approach, you maintain accurate data capture without AI hallucination, while giving users intuitive, navigable forms that feel natural within the Agent conversation flow. Try it out and share what you build. Post questions on the Salesforce Developer Community or Stack Overflow.

Resources

• Documentation: Transaction Dispute Management Intake in Financial Services Cloud
• Documentation: Discovery Framework
• Video: Discovery Framework for Financial Services Cloud
• Developer Guide: Enhance the Agent UI with Custom LWCs and Lightning Types 

About the author

Aditya Bhansali is a Lead Member of Technical Staff in the Agentforce Financial Services organization, where he leads Salesforce engineering teams in building enterprise products on the Salesforce Platform. He shares updates on LinkedIn.

The post Capture Rich Data within Agent Conversations by Using Discovery Framework appeared first on Salesforce Developers Blog.