What if you could skip all of that and just describe what you want? In this post, we’ll walk through how the new Mobile Skills can accelerate your mobile app development, from initial project setup all the way through building real features and functionality.

Getting past the mobile learning curve

Most Salesforce Developers are comfortable with business logic. What trips them up is everything around it, including OAuth handshakes, SDK version mismatches, Xcode build settings, and Gradle configurations. Native mobile development involves significant infrastructure overhead that has nothing to do with the app’s actual purpose, and it can take days just to get a project into a state where real work can begin.

Mobile Skills take that entire bootstrapping phase off your plate. They generate a clean, modern project structure with authentication and SDK integration already wired up, so your first task is building a feature, not fighting a toolchain.

Built for developers who live in IDEs, not GUIs

Mobile Skills output standard source files organized the way a professional iOS or Android project should be. You get a real Xcode workspace or Android Studio project that you can read, refactor, and push to Git. The code is yours from the moment it’s generated.

Skills: How agents go from generic to useful

An Agent Skill is a packaged, reusable capability that an AI agent can invoke. Think of it as a well-documented function your AI assistant knows how to call, except instead of returning a string, it can scaffold a project, generate code, configure SDKs, or run commands on your behalf.

Each skill ships with:

• A clear contract — what it does, what inputs it expects, what it produces
• Domain knowledge — the patterns, APIs, and conventions for the task
• Executable instructions — so the agent can actually do the work, not just talk about it

Skills are how you turn a general-purpose AI into a domain expert. A generic LLM might know that the Salesforce Mobile SDK exists. A skill knows the right project template, the right dependencies, and exactly which boilerplate to generate for your org’s auth flow.

Introducing Mobile Skills

Mobile Skills give your AI agent everything it needs to build production-quality native mobile apps using Salesforce Mobile SDK, the same SDK that powers Salesforce mobile apps.

Here’s what the Mobile Skills are capable of today:

• Create a Mobile SDK app from scratch

Describe the app you want, for example “Build me a native iOS app for field reps with offline access to Accounts and Contacts”, and Mobile Skills scaffold a fresh Mobile SDK project, configured for your org, ready to run.

• Add Mobile SDK to an existing app

Already have an iOS or Android app? Mobile Skills can integrate Mobile SDK into your existing codebase without forcing you to start over. They handle dependencies, configuration, and the integration patterns that often trip people up.

• SmartStore sync

Configure encrypted, on-device storage with a single prompt. Mobile Skills know the soup definitions, indexing strategies, and query patterns that work, so there’s no more digging through docs to figure out what IndexSpec to use.

• Mobile sync

Set up bidirectional sync between your app and your org with the right sync targets, sync down/up policies, and conflict resolution, and do it all declaratively, from a prompt.

• Offline-first behavior

Tell your agent “this app needs to work offline” and Mobile Skills wire up the right combination of SmartStore + MobileSync, sets up appropriate cache policies, and handles the edge cases (for example, network transitions, failed syncs, and dirty records) that can take weeks to get right by hand.

• Authentication and login

Basic auth, OAuth flows, and login screens are all generated correctly the first time, following the secure patterns Salesforce recommends.

• Biometric authentication

Add Face ID, Touch ID, or Android biometrics to your app with a single instruction.  Mobile Skills handles the platform differences, the fallback flows, and the security best practices.

• Agentforce chat panel integration

Drop a fully-wired Agentforce chat experience into your mobile app. Your end users get an intelligent, contextual agent inside their app, configured to talk to your org, and you don’t have to read a single integration guide.

Getting started with Mobile Skills

Mobile Skills are part of forcedotcom/sf-skills, the open-source collection of Salesforce Agent Skills for platform development. The repository is public: you can browse it, fork it, contribute to it, and pull skills into whatever agentic tool you’re already using. Think of it as a growing catalog of things AI agents should know how to do on Salesforce.

Works wherever you work

Skills in this repository follow the open Agent Skills specification, which means they aren’t locked to a single tool. Mobile Skills work across surfaces, whether that’s Agentforce Vibes (available out of the box), Claude Code, Cursor, OpenCode, Codex, or any other agent that supports the spec. To install in a code agent, just run:
npx skills add https://github.com/forcedotcom/sf-skills --skill mobile-apps-create

How it works under the hood

/mobile-apps-create is the primary entry point — a lightweight orchestrator that lives in sf-skills. When you describe what you want to build (for example, “I need a Salesforce mobile app with offline sync”), the orchestrator determines which SDK family and platform you’re targeting, then routes your request to the appropriate individual skill that handles the actual work.

A real example

It starts with a single sentence. In Agentforce Vibes, describe the app that you want to build. In this example, I’m building an iOS app to manage a store inventory and sync the data back to Salesforce. 

Agentforce Vibes picks up the intent, activates Mobile Skills under the hood — handling Mobile SDK authentication, SmartStore for offline data, and MobileSync for bidirectional Salesforce sync — and starts generating the full app.

Within moments, the app is built and running in the iOS simulator. The first thing you see is the standard Salesforce OAuth login screen, secure, familiar, and fully functional. Mobile SDK handles the entire authentication flow, including token management, refresh, and session persistence. No custom auth code required.

After login, the app lands on a home screen with a clean product inventory dashboard. Counts, categories, and visual summaries are all pulled live from the Salesforce org. This isn’t a mockup; it’s real data flowing through MobileSync’s soup-to-cloud sync pipeline, displayed in a native SwiftUI interface.

Tapping into the Products tab reveals the full inventory list, with each item editable. You can add a new product, update a quantity, or change a description; every modification syncs back to Salesforce automatically. Even if the device goes offline, SmartStore caches changes locally and MobileSync pushes them upstream when connectivity returns.

But why stop at inventory management? Back in the Agentforce Vibes prompt, I went ahead and asked the agent to embed an Agentforce chat panel. Just like that, the app now includes a native Agentforce conversational interface right inside the app. The Agentforce SDK handles the agent connection, conversation threading, and action orchestration, all wired up from a single prompt.

Store Managers can use the Agentforce chat to ask questions like “Which products are low in stock?” or ask it to refill stock without ever leaving the app. It’s not just an app anymore; it’s an AI-powered mobile experience, built in minutes.

What’s Next

The Mobile Skills you see today are the foundation. We’re actively expanding the library to cover more SDK capabilities, more frameworks, and richer end-to-end app generation flows. If you’re building mobile apps on Salesforce, this is the moment to plug AI into your workflow, not as a typing assistant, but as a companion engineer who already knows the platform.

Your feedback matters! Try Mobile Skills, share your feedback, and tell us what to build next.

Resources:

• Explore sf-skills on GitHub
• Get Started with Agentforce
• Mobile SDK Developer Guide
• Mobile SDK GitHub repository

About the author

Shalini Jain is a Director of Product Management at Salesforce, where her primary focus lies in shaping the Mobile Platform Experience for developers through AI-driven innovation. Her current initiatives are heavily invested in enhancing developer productivity by bringing agentic AI capabilities directly into the mobile development workflow, as evidenced by the tools highlighted throughout this blog post. Furthermore, she is spearheading new features in Mobile SDK to further streamline and optimize how developers build, test, and ship mobile apps, with the ultimate goal of delivering a truly seamless and intuitive experience for all Salesforce mobile developers.

The post Build Native Mobile Apps Within Minutes Using Agent Skills appeared first on Salesforce Developers Blog.

Defining state in LWC with defineState

A state manager is a dedicated JavaScript module that encapsulates a related set of data (the “state”) and the actions that operate on it. You create one with the defineState function from @lwc/state, passing a setup function. The setup function’s first argument is an object of building blocks: atom, computed, and setAtom. defineState returns a factory; any arguments you pass when you call it flow through to your setup function after that object, so you can parameterize each instance:

• An atom is a reactive “atomic” value, which is essentially a wrapper around a piece of data that LWC can use to make components and other state managers reactive to changes in that data.
• A computed is a lazily-evaluated derivation that recalculates only when its atom dependencies change.
• setAtom is used whenever you need to modify state.

import { defineState } from '@lwc/state';

export const createCounter = defineState(({ atom, computed, setAtom }, initialCount = 0) => {
    const count = atom(initialCount);
    const doubled = computed([count], (countValue) => countValue * 2);


    const increment = () => setAtom(count, count.value + 1);


    return { count, doubled, increment };
});

Any component that references count or doubled in a reactive context is automatically re-rendered after increment runs. Computed values recompute lazily and only when their inputs change, and multiple setAtom calls in the same tick are batched into a single notification cycle, so you get reactivity without the re-render churn.

Sharing state across a component tree with fromContext

State managers go beyond a single component. You can create an instance at the top of a component tree and consume it in a descendant component below using fromContext, with no prop drilling, no event handling, and no pub/sub plumbing:

Example code for the top-level component that instantiates the state manager:

import createShopStateManager from 'x/shopState';

export default class App extends LightningElement {
    shopState = createShopStateManager();
}

Example of a descendant component that reads the same instance via LWC context:

import { LightningElement } from 'lwc';
import { fromContext } from '@lwc/state';
import createShopStateManager from 'x/shopState';

export default class Cart extends LightningElement {
    shopState = fromContext(createShopStateManager);

    get cartTotal() {
        return `$${this.shopState.value.cartTotal.toFixed(2)}`;
    }
}

Built-in state managers for Salesforce data

Salesforce ships a collection of state managers in the lightning namespace that expose Salesforce data and metadata through the Lightning Data Service. Each one presents a uniform shape:

• status (”unconfigured” | ”loading” | ”loaded” | ”error”)
• data
• error
• setter functions for configso using and composing them is straightforward.

Available state managers expose record, objectInfo, layout, and related list data. Because state managers can be nested and wired together with computed, you can build sophisticated, fully reactive data waterfalls, for example: fetch a record to discover its record type, then fetch the matching layout, then fetch the full record using the layout’s fields.

Example of a component that consumes a lightning/stateManagerRecord:

import { LightningElement, api } from 'lwc';
import { getFieldValue } from 'lightning/uiRecordApi';
import createRecordStateManager from 'lightning/stateManagerRecord';
import ACCOUNT_NAME_FIELD from '@salesforce/schema/Account.Name';
import ACCOUNT_INDUSTRY_FIELD from '@salesforce/schema/Account.Industry';

export default class AccountCard extends LightningElement {
    _recordId;

    // The built-in state manager instance. Config takes the schema field refs;
    // recordId is supplied later via the @api setter.
    state = createRecordStateManager({
        fields: [ACCOUNT_NAME_FIELD, ACCOUNT_INDUSTRY_FIELD]
    });

    @api
    set recordId(id) {
        this._recordId = id;
        // Updaters live on the frozen outer shape, so go through .value.
        this.state.value.setRecordId(id);
    }
    get recordId() {
        return this._recordId;
    }

    get displayLabel() {
        const { status, data } = this.state.value;
        if (status !== 'loaded') return 'Loading…';
        const name = getFieldValue(data, ACCOUNT_NAME_FIELD) ?? 'Unknown';
        const industry = getFieldValue(data, ACCOUNT_INDUSTRY_FIELD) ?? '';
        return industry ? `${name} — ${industry}` : name;
    }
}

See state managers in action

State managers bring a modern, reactive data-flow pattern to LWC that scales from a single component to a full application. Because state managers are plain JavaScript modules with no DOM dependency, you can unit-test them with Jest without mounting a component. You can reuse the same state module across multiple component trees. And because consumers read values from the state manager’s public shape rather than reaching into its internals, you can refactor how state is stored without updating every consumer. Additionally, with the built-in UI API state managers, you get that same shape for Salesforce data out of the box. Note: state managers are available in Lightning Experience, but not yet supported in Experience Cloud.

To help you get started, we’ve published two complete examples in the forcedotcom/state-management GitHub repository:

• simple-store: A standalone shopping-cart application (demoed at TDX in March 2026) that shows how multiple components can read and mutate the same state manager entirely through context, with no properties or events. You can run it live on StackBlitz.
• platform-state-managers: A Salesforce DX project that builds a layout-driven record detail panel using the record and layout state managers. The source is heavily commented, and is the best place to learn the basics.

More resources

Ready to start managing your state? Here are additional resources you need to dive in:

• Developer Documentation: Manage State Across LWC Components
• GitHub repository (forcedotcom/state-management): Find the platform-state-managers and simple-store examples.
• Live playground (Simple Store on StackBlitz): Explore a full state-manager app in your browser.

About the Authors

Mike Burr is a Principal Member of Technical Staff at Salesforce from the Lightning Data Service team. When he’s not building client data libraries, he’s busy tweaking his home automation and listening to audiobooks.

Ben Sklar is a Director of Product Management at Salesforce responsible for UI API, GraphQL API, Lightning Data Service, and AI Developer Kit. Ben is a major fan of GraphQL, but when not using GraphQL, you can find him playing ultimate frisbee or skiing during the winter. Follow him on LinkedIn.

The post LWC State Managers: Share Reactive State Across Components appeared first on Salesforce Developers Blog.

Whether you’re a developer building MCP servers or an admin managing them, understanding the security model helps you control who can access what, when, and how. In this post, we’ll cover authentication, authorization, permission controls, and logging best practices for Salesforce Hosted MCP Servers.

Understanding the Salesforce Hosted MCP Server security model

The Salesforce MCP security model has three layers:

1. Authentication: Verifies who’s making the request
2. Authorization: Determines what they’re allowed to do
3. Permission controls: Enforce granular access at the object and field level when working with the primitives (tools, prompts and resources) exposed by the server

And, in addition to these security layers, logging tracks all activity for audit and compliance.

The first two layers are directly linked to the MCP standard and the third (permission controls) is specific to the Salesforce Platform. Each security layer builds on the previous one. You can’t authorize someone until you know who they are. You can’t enforce permissions without authorization rules.

Understanding how these layers and logging work together helps you build a defense-in-depth strategy. Let’s look at each layer in detail.

Authentication: Verifying identity

Authentication is the first line of defense. It answers the question: “Who are you?”

Authentication and authorization are technically defined as optional for MCP implementations as per the MCP specification, but we will assume for the rest of this post that it’s mandatory in an enterprise context given that without proper security, unauthorized users could access sensitive data or trigger unwanted operations.

MCP specifies OAuth 2.0 as its authentication and authorization mechanism. It supports only a subset of OAuth 2.0 — not every authorization flow or grant type is available. Popular clients like Claude and ChatGPT support fewer flows than Salesforce does.

While MCP is fairly recent, OAuth 2.0 has been around for more than a decade and the Salesforce Platform has a number of mechanisms to integrate with OAuth, whether it acts as a client or a server. This means that, as a Salesforce Developer, you do not have to implement OAuth security. Instead, you control it declaratively through an external client app (ECA).

We strongly recommend creating a dedicated ECA per MCP client (one for Claude, one for ChatGPT, one for Cursor, etc.) rather than sharing a single ECA across multiple clients. This helps with controlling access and auditing the client’s activity.

When it comes to Salesforce Hosted MCP Servers, we only support the authorization code flow through the ECA. This means that users have to authenticate with Salesforce when connecting to the MCP server. Their individual Salesforce user account is tied to the MCP session.

Notes:

• There’s no option to specify a service account with a principal user, such as an integration user, to be used across all sessions. This is an anti-pattern that customers should avoid.
• At this time, there’s no plan to allow machine-to-machine flows. The human remains in the loop to connect to the org and grant access to the MCP tools.

By default, any user from your org can connect to your ECA and access the MCP servers. However, you can specify authorization rules to control the access.

Authorization: Controlling access

Authorization tells you what the user can do. Once a user is authenticated, Salesforce evaluates their permissions to determine which resource they can access.

There are a number of mechanisms that you can put in place to control authorization.

Authorize access with OAuth scopes

The first level of authorization to access specific resources is handled by OAuth scopes when configuring an ECA.

The new “Access Salesforce hosted MCP servers (mcp_api)” scope grants access to Salesforce Hosted MCP Servers. We’ve released this scope to avoid exposing the “Manage user data via APIs (api)” scope that grants full access to the Platform APIs (REST, Tooling, Metadata, etc.).

As a general rule, it’s preferable to only expose a limited set of “safe” operations to agents via MCP rather than to allow full API access.

Restrict access to pre-authorized users

With the default ECA configuration, all users from your org can authenticate and access the MCP servers. You can restrict access to specific pre-authorized users by configuring an app policy. This lets you select users with specific profiles or permission sets.

For example, this configuration only allow users with the “MCP Client User” permission set to connect to the ECA:

Enforce IP restrictions

In addition to restricting the use of the ECA to specific users, you can apply IP restrictions by only specifying IP ranges to connect. These restrictions are enabled in the default ECA configuration under App Authorization.

You can specify trusted IP ranges for all users in the Network Access setup menu or for specific user profiles.

Shorten refresh token lifetime

Once a user logs in with the ECA, they acquire an access token that is passed to all subsequent MCP operations. The token must be refreshed after its lifetime expires.

The default token lasts for a year, but you can control the duration of the token lifetime and reduce it in production. You can do this to limit the risk of token theft and reuse for malicious intents. To control the token lifetime, go in the ECA configuration and look for Refresh Token Policy under App Authorization. Our documentation includes recommendations on how to improve security in this area.

Revoke access

Should you need to revoke tokens for your ECA before they expire, go to Setup, search for OAuth Usage, select your ECA, and revoke individual tokens or run a bulk revoke operation.

Activate MCP servers

By default, all MCP servers are inactive. Only activate the ones that you intend to expose to agents.

For example, here we’ve only activated a custom server and two standard servers:

Annotate MCP tools

While not strictly a security measure, it’s a best practice to annotate MCP tools that you expose to provide hints about their behavior. Doing so lets agents know how they should use the tools. For example, should the agent ask the user for confirmation when running potentially destructive operations, such as deleting a record, or whether a tool can safely be run multiple times.

Note: Support for MCP tool annotations is optional on the client side and these may not be enforced by all agents.

Permission controls: Granular access management

You cannot restrict access to a specific MCP server through the ECA configuration, but you control access to the tools that compose those servers.

MCP tools run with the same permissions as the user who authenticated with the ECA. This means that our core security model applies at all levels:

• Object-level access (CRUD permissions)
• Field-level security (FLS) restrictions
• Record sharing rules

It’s also possible to implement custom tools with Agentforce, Apex, or Flow to address unique security requirements. If you choose this path, always follow security best practices.

Be sure to work with permission sets to protect sensitive operations and follow the principle of least privilege. Grant only the permissions that users need to do their jobs. Review permissions regularly and remove access that’s no longer required.

Also, test permissions before deploying to production. For example, run Apex tests and Flow tests on your MCP tools with the runAs method to simulate the behavior of users with different access levels.

Logging: Tracking access

Logging creates an audit trail of who accessed what and when. This is essential for security monitoring, compliance, and troubleshooting.

All actions that are performed by the MCP tools are attributed to the user that connected to the ECA in audit trails. Salesforce automatically logs MCP server activity using Event Monitoring.

To access the logs, navigate to Setup and search for Event Log File Browser. Filter Event Type on “API Total Usage”. You can identify MCP traffic by filtering the event log CSV files for rows where the API_CLIENT_CATEGORY column matches SALESFORCE_HOSTED_MCP. You’ll see the users that called the MCP tools and the affected objects (entities) among other details.

Review logs regularly. Look for errors thanks to STATUS_CODE or unexpected access patterns with USER_NAME or CLIENT_IP. These can indicate security issues or misconfigured permissions.

Conclusion

In this post, we’ve reviewed how to secure Salesforce Hosted MCP Servers, and we’ve covered all of the components that form this layered security architecture, including:

• Authentication verifies identity
• Authorization controls what tools users can access
• Permission controls enforce granular data access
• Logging creates an audit trail for compliance and security monitoring

It’s now up to you to implement these security best practices and protect your data while shipping powerful MCP tools that agents can use.

Resources

• Documentation: Salesforce Hosted MCP Servers
• Documentation: Manage MCP Servers in API Catalog
• Documentation: External Client Apps
• Documentation: Permission Sets
• GitHub: Community Wiki

About the author

Philippe Ozil is a Principal Developer Advocate at Salesforce, where he focuses on the Salesforce Platform. He writes technical content and speaks frequently at conferences. He is a full-stack developer and enjoys working with APIs, DevOps, robotics, and VR projects. Follow him on X, LinkedIn, and Bluesky, and check out his GitHub projects.

The post How to Secure Salesforce Hosted MCP Servers appeared first on Salesforce Developers Blog.

Whether adapting to regulatory shifts or launching new products, account teams can use BRP to implement fresh metrics in minutes, surfacing real-time, actionable insights for every client relationship manager. In addition, BRP supports organizational agility by shifting logic ownership from engineering tickets to a simpler admin configuration. Clear extension points enable developers to customize BRP further using Flow, Apex, or Lightning web components.

In this blog post, we’ll walk through the BRP architecture and the core data model. We’ll then demonstrate how admins can configure BRP , and how business users can set up and use the system. Finally, we’ll explore how to extend BRP using Apex business logic and document generation.

What Business Relationship Plan is (and why it matters)

Business Relationship Plan is the layer in Agentforce Financial Services that sits on top of the AccountPlan object in Salesforce. It gives organizations a structure for plan records, objectives, measures, and tasks, and it allows them to extend this model with Flow, Apex, and UI components.

At a high level, BRP connects:

• Plan: Account-level strategy record
• Objectives: Prioritized outcomes with owners
• Measures: Key performance indicators (KPIs) and targets
• Action Plan: Action items tied to objectives
• Visibility: Progress tracking across accounts

When we enable Einstein features, we can also add interaction summaries for better context before meetings.

Account Plans vs. BRP: What to use when

While Account Plans serve standard, linear management needs, Business Relationship Plan delivers a highly extensible architecture specifically engineered for sophisticated, multi-outcome strategies and deep platform integration.

Business Relationship Plan architecture at a glance

The architecture of Business Relationship Plan spans four layers: Data (Plan, Objective, Measure records), Experience (Lightning pages and Flexcards), Orchestration (Flow, Apex, Omniscript), and Insight (Einstein summaries and analytics). 

1.   Data layer: Plan, Objective, Measure, and Task records with standard and custom fields
2.   Experience layer: Lightning pages, Flexcards, and Strategic Tracker components
3.   Orchestration layer: Flow, Omniscript, and Apex automation
4.   Insight layer: Einstein summaries and dashboard analytics

The diagram below shows how data flows between BRP’s four layers and their components: the Data layer with sObjects, the Experience layer with Lightning components, the Orchestration layer with Flow and Apex, and the Insight layer with Einstein and dashboards.

BRP data model: Core objects and relationships

Business Relationship Plan offers a technical structure for Account Plan records, objectives, measures, and action plans, connecting client account goals directly to Financial Deal, Opportunities, Cases, and Contacts within the Salesforce data model.

Core objects

While each of the Account Plan entities contains numerous fields, we’ll focus here on the fundamental fields that are essential across all entities to help you understand the core data structure.

AccountPlan: The root planning object.

• Standard fields: Name, AccountId, Status, StartDate, EndDate
• Key relationships: Account (lookup), Owner (lookup)

AccountPlanObjectiveCategory: Categories for classifying objectives.

• Standard fields: Name, Description, StartDate, EndDate, IsActive

AccountPlanObjective: Strategic goals within a plan.

• Standard fields: Name, AccountPlanId, Priority, Status, Owner, StartDate, EndDate, Description
• Key relationships: AccountPlan (master-detail), Owner (lookup), AccountPlanObjCategory (lookup)

AccountPlanObjectiveMeasure: Quantifiable KPIs tracking objective progress.

• Standard fields: Name, AccountPlanObjectiveId, ValueType, TargetValue, CurrentValue
• Key relationships: AccountPlanObjective (master-detail), AccountPlanObjMeasCalcDef (lookup)

AccountPlanObjectiveMeasureRela: Links measures to related records.

• Standard fields: Name, AccountPlanObjectiveMeasureId, ReferenceRecordId
• Key relationships: AccountPlanObjectiveMeasure (master-detail), ReferenceRecord (multi-lookup to Opportunity, Financial Deal, Case, Contact, Campaign, etc.)

ActionPlan: Structured task-based execution plans.

• Standard fields: Name, ActionPlanType, StartDate, EndDate
• Key relationships: Target (multi-lookup)

ActionPlanItem: Individual tasks within an action plan.

• Standard fields: Name, ActionPlanId, IsRequired, DisplayOrder, DependencyStatus
• Key relationships: ActionPlan (master-detail), ActionPlanItem (multi-lookup)

Task: Action items tied to objectives.

• Standard fields: Subject, Status, Priority, Due Date, Assigned To
• Key relationships: What (lookup to Objective)

Sample SOQL query

The query below retrieves active plans with nested objectives and measures, which is useful for building custom dashboards.

SELECT Id, Name, Account.Name, Status, StartDate, EndDate,                                                                                                                                                                                                                                                                                                                                                                                
      (SELECT Id, Name, Priority, Status, Owner.Name,
          (SELECT Id, Name, TargetValue, CurrentValue                                                                                                                                                                                                                                                                                                                                                         
           FROM AccountPlanObjectiveMeasures)                                                                                                                                                                                                                                                                                                                                                                                               
       FROM AccountPlanObjectives                                                                                                                                                                                                                                                                                                                                                                                                           
       ORDER BY Priority, CreatedDate)                                                                                                                                                                                                                                                                                                                                                                                                      
  FROM AccountPlan                                                                                                                                                                                                                                                                                                                                                                                                                          
  WHERE Status = 'Active'                                                                                                                                                                                                                                                                                                                                                                                                                   
    AND Account.Industry = 'Banking'                                                                                                                                                                                                                                                                                                                                                                                                        
  ORDER BY StartDate DESC                                                                                                                                                                                                                                                                                                                                                                                                                   
  LIMIT 100

Calculation definitions in Business Relationship Plan

A Calculation Definition is a core configuration record in BRP that defines the logic for platform-led aggregations. It establishes a technical framework with three fundamental pillars:

• Target object: Identify the specific record type for data aggregation
• Target field: Specify the numeric or currency value to be rolled up
• Rollup type: Define the mathematical operation (Sum, Count, Min, or Max)

Furthermore, users can implement conditional logic to filter the underlying data set, ensuring that only qualifying records contribute to the final metric. Once this setup is complete, client relationship managers can leverage these definitions across multiple Account Plan measures without writing a single line of code.

Summary of roles

This collaborative framework ensures that while admins govern the formula, the platform manages the data, and users focus on results. That is the power of Calculation Definitions.

Let’s now take a look at the steps an admin would take to set up calculation definitions in Agentforce Financial Services. Once set up, we’ll then look at how a business user would use the system.

The admin experience: Configuring the engine

The initial setup phase creates a reusable asset for the entire organization. Once published, these definitions become standard options for all team members during measure creation. 

As an admin, you would follow these steps to configure BRP.

Step 1: Access configuration

Navigate to Setup -> Sales Account Plans and you will see the calculation definition section. You will see both out-of-the-box (OOTB) logic and custom configurations tailored to your specific business requirements.

Step 2: Define the data parameters

Click on New Calculation Definition and populate the following essential fields:

• Identity: Assign a Name and unique API Name for the definition
• Context: Provide a clear description, so end users understand what the metric represents
• Source: Select the Target Object (e.g., Financial Deal) and the corresponding Target Field
• Logic: Choose the Rollup Type; the platform automatically infers the data type from your field selection

Step 3: Implement conditional filters

Admins can apply up to five conditions to refine the calculation scope. For example, you might exclude records where the status is “Inactive” or filter by specific transaction thresholds to ensure metric accuracy.

Step 4: Lifecycle Management

New definitions begin in Draft mode for review. Transitioning to Active status locks the core configuration to prevent unintended changes to live metrics, ensuring consistency across quarterly planning cycles.

The business user experience: Operationalizing strategy

Once activated, these technical definitions are handed off to client relationship managers to drive daily business outcomes.

Business users would follow these steps:

Step 1: Establish the plan hierarchy

Users begin by creating an Account Plan and defining high-level Objectives, such as increasing portfolio retention or growing fee income.

Step 2: Link measures to logic

For each Objective, the user adds a measure. They define the name and target value, then select the appropriate calculation definition from the dropdown to assign the aggregation logic.

Step 3: Associate records 

The user manually associates relevant records (e.g., Financial Deals) using the AccountPlanObjectiveMeasureRela records. This flexible mapping allows single records to contribute to multiple plans without limit.

Step 4: Automate orchestration

The platform executes a nightly scheduled job that processes these associations, applies admin-defined conditions, and updates the Current Value field automatically, ensuring that fresh data is available every morning.

Architecting for performance: The daily cadence

Agentforce Financial Services utilizes a batch approach for these calculations to maintain optimal system performance. This design ensures that today’s updates to deals or record associations are consistently reflected in the next day’s planning metrics without creating unnecessary overhead.

Workflow example: Tracking Q3 deal revenue

Consider a scenario where a financial advisor tracks transaction revenue for a high-net-worth client.

Phase 1: Admin configuration

1. Admin creates an “Active Deal Transaction Value” definition targeting the Financial Deal object.
2. Logic is set to Sum the transaction field with a filter for active status.

Phase 2: Execution

1. Monday: The advisor sets up the Account Plan and links eight deals to a new measure.
2. Tuesday: The system reflects a $1.45M current value automatically.
3. Quarter-End: As new deals close and are associated, the platform tracks the revenue growth until the $2M goal is surpassed.

Extend Business Relationship Plan with Apex

For complex business logic, developers can use Apex to extend BRP functionality. This allows you to implement sophisticated patterns beyond Flow capabilities, such as a nightly scheduled job that computes weighted health scores (on a 0–100 scale) for objectives by analyzing progress from baseline to target. Such automation can programmatically refresh status labels like On Track, At Risk, or Off Track, while utilizing batchable Apex to maintain performance for large-scale deployments exceeding 2,000 records.

Prerequisites

Before implementing Apex extensions for BRP, ensure that your org meets these requirements:

• Salesforce Edition: Enterprise Edition or higher
• Financial Services Cloud license: Active FSC license
• Agentforce Financial Services: Enabled in org settings
• Permission sets: AccountPlan object permissions (Read, Create, Edit) assigned to users
• Omnistudio runtime: Enabled for Flexcards and Omniscript functionality
• Custom field access: Ability to create custom fields on AccountPlanObjective and AccountPlanObjectiveMeasure objects

The following example shows how to customize BRP to track objective health scores.

Example: Calculate objective health score

To prepare your organization for the Apex calculation, create these custom fields:

• On AccountPlanObjectiveMeasure:
  • BaselineValue__c (Text, 255): Stores the starting value for progress calculation
  • Weight__c (Number, 5,2): Defines the relative importance (weight) of the measure in the objective’s health score
• On AccountPlanObjective:
  • HealthScore__c (Number, 5,2): Stores the calculated weighted health score (0–100)
  • Status picklist update: To use the determineHealthStatus method, add the values On Track, At Risk, and Off Track to the AccountPlanObjective.Status picklist
• Crucial Data Note: Ensure that the ValueType field (Number, Currency, or Percent) is set on AccountPlanObjectiveMeasure records before TargetValue and CurrentValue can be persisted.

/**
 * Computes a weighted health score per Account Plan Objective from its measures,
 * then sets HealthScore__c and a text Status from score bands.
 */
public class BRPObjectiveHealthCalculator {

    /**
     * Loads objectives (and related measures), aggregates progress by weight,
     * and updates objectives that have at least one valid weighted measure.
     *
     * @param setOfObjectiveIds Ids of AccountPlanObjective records to recalculate; no-op if null/empty.
     */
    public static void calculateHealthScores(Set setOfObjectiveIds) {
        if (setOfObjectiveIds == null || setOfObjectiveIds.isEmpty()) {
            return;
        }

        // Child subquery: FROM clause must be the child relationship API name + __r (verify in object manager).
        List objectives = [
            SELECT Id, Name, HealthScore__c, Status,
                   (SELECT Id,
                           BaselineValue__c,
                           TargetValue,
                           CurrentValue,
                           Weight__c
                    FROM AccountPlanObjectiveMeasures)
            FROM AccountPlanObjective
            WHERE Id IN :setOfObjectiveIds
        ];

        // Only objectives we actually change are DML’d to avoid unnecessary updates/triggers.
        List objectivesToUpdate = new List();

        for (AccountPlanObjective obj : objectives) {
            // Running totals for weighted average of per-measure progress (0–100 each).
            Decimal weightedScore = 0;
            Decimal totalWeight = 0;

            for (AccountPlanObjectiveMeasure measure : obj.AccountPlanObjectiveMeasures) {
                if (isValidMeasure(measure)) {
                    Decimal progress = calculateProgress(measure);
                    // Null weight defaults to 1 so the measure still counts equally if unspecified.
                    Decimal weight = measure.Weight__c != null ? measure.Weight__c : 1;

                    weightedScore += progress * weight;
                    totalWeight += weight;
                }
            }

            // Skip update when no valid measures contributed weight (avoids divide-by-zero and blank scores).
            if (totalWeight > 0) {
                // Weighted average progress, expressed on a 0–100 scale for storage/display.
                obj.HealthScore__c = (weightedScore / totalWeight);
                obj.Status = determineHealthStatus(obj.HealthScore__c);
                objectivesToUpdate.add(obj);
            }
        }

        if (!objectivesToUpdate.isEmpty()) {
            update objectivesToUpdate;
        }
    }

    /**
     * A measure is included only when baseline, target, and current are all present,
     * so progress and comparisons are well-defined.
     */
    private static Boolean isValidMeasure(AccountPlanObjectiveMeasure measure) {
        return measure.BaselineValue__c != null
            && measure.TargetValue != null
            && measure.CurrentValue != null;
    }

    /**
     * Linear progress from baseline toward target, as a percentage (0–100).
     * Values are coerced with Decimal.valueOf in case the fields are numeric types other than Decimal.
     */
    private static Decimal calculateProgress(AccountPlanObjectiveMeasure measure) {
        Decimal baseline = Decimal.valueOf(measure.BaselineValue__c);
        Decimal target = Decimal.valueOf(measure.TargetValue);
        Decimal current = Decimal.valueOf(measure.CurrentValue);

        // Degenerate case: no movement defined; treat as fully achieved to avoid division by zero.
        if (target == baseline) {
            return 100;
        }

        // Raw % along the line from baseline to target; can exceed 0–100 before clamping.
        Decimal progress = ((current - baseline) / (target - baseline)) * 100;
        // Clamp so a single outlier measure cannot push the aggregate beyond 0–100 contribution.
        return Math.min(Math.max(progress, 0), 100);
    }

    /**
     * Maps stored score to a simple status label for reporting/UI.
     */
    private static String determineHealthStatus(Decimal score) {
        if (score >= 80) {
            return 'On Track';
        }
        if (score >= 60) {
            return 'At Risk';
        }
        return 'Off Track';
    }
}

Usage: Call this class from a scheduled Apex job to recalculate health scores nightly.

public class BRPHealthScoreScheduler implements Schedulable {
    public void execute(SchedulableContext ctx) {
       Set objectiveIds = new Set();
      
       for (AccountPlanObjective obj : [
           SELECT Id
           FROM AccountPlanObjective
           WHERE Status = 'In Progress'
           AND AccountPlan.Status = 'Active'
       ]) {
           objectiveIds.add(obj.Id);
       }
      
       if (!objectiveIds.isEmpty()) {
           BRPObjectiveHealthCalculator.calculateHealthScores(objectiveIds);
       }
    }
}

Schedule with: System.schedule('BRP Health Score Calculator', '0 0 2 * * ?', new BRPHealthScoreScheduler());.

Note: For orgs with more than 2,000 active objectives, refactor this into a Database.Batchable class with a batch size of 200. The calculateHealthScores method already accepts a Set<Id>, so the batchable execute() method can pass each batch directly.

global class ObjectiveHealthScoreBatch implements Database.Batchable {

    global Database.QueryLocator start(Database.BatchableContext bc) {
        return Database.getQueryLocator(
            'SELECT Id FROM AccountPlanObjective'
        );
    }

    global void execute(Database.BatchableContext bc, List scope) {
        Set objectiveIds = new Map<Id, SObject>(scope).keySet();
        calculateHealthScores(objectiveIds); // already accepts Set
    }

    global void finish(Database.BatchableContext bc) {
        // optional: send notification, log results
    }
}

Extend Business Relationship Plan with Document Generation

Salesforce Document Generation enables organizations to automatically create Word documents and PowerPoint presentations from Account Plan data. By placing the Summary Documents component on the Account Plan record page, developers can allow users to generate documents on-demand from pre-built templates with merge fields and conditional logic. Generated documents pull live data (objectives, measures, activities, related records) and are stored in Salesforce, where they can be:

• Exported: Download as native .docx/.pptx formats or convert to PDF
• Shared: Email as attachments or share via public/private links
• Printed: Download and print for client meetings or internal reviews
• Archived: Store for compliance and audit trails
  

This simple extension adds a lot of value and can be used for executive summaries, quarterly business reviews, and stakeholder presentations.

Best practices for developers

• Review existing OOTB capabilities first: Before building custom components, check available features like Flexcard Selector, Objectives Component, Action Plans, and Summary Documents for complete out-of-the-box functionality to avoid duplicate development
• Keep objective definitions specific and time-bound: Use validation rules to enforce date ranges and clear naming conventions
• Limit KPIs to meaningful indicators: Avoid measure proliferation; focus on three to five key measures per objective
• Build automation for repetitive tasks: Use Flow for measure reminders and status updates

Conclusion

When essential account data is static and siloed, annual account planning becomes more challenging and can easily fail.Business Relationship Plan gives financial services organizations a technical and operational model that they can run every week. With the right data model, UI, and automation, account teams can track goals in real time, act faster, and be more productive.

For developers, BRP provides a solid foundation with clear extension points. Whether you’re building Flow automation, Apex business logic, or custom LWC components, the platform supports continuous planning workflows that replace static annual planning cycles.

Resources

• Business Relationship Plan Overview
• Enable Business Relationship Plan
• Business Relationship Plan Setup Guide
• Add FlexCard Component
• Configure the Pre-Built Account Plan Lightning Page 
• Configure Fields Specific to BRP
• Manage User Access for BRP 
• Sales Account Plans Overview
• Account Plans Setup
• Strategic Tracker with Sales Action Plans 
• Einstein Summaries for BRP
• Salesforce Developers sample apps on GitHub

About the author

Vignesh Damodharan is a Lead Member of Technical Staff with Agentforce Financial Services, where he leads Salesforce engineering teams building enterprise products on the Salesforce Platform. Follow him on LinkedIn.

The post Build Continuous Planning Systems in Agentforce Financial Services appeared first on Salesforce Developers Blog.

Many Salesforce Developers want a repeatable, design-first lifecycle for agent development. The Headless 360 approach pairs a coding agent like Claude Code, Codex, or Agentforce Vibes with Agent Skills, so you can design, build, deploy, test, and debug from a single plain-language conversation. You stay the designer; the coding agent does the development. 

In this post, we’ll look at how to set up Salesforce Agent Skills, scaffold a project and connect an org, design before you build, generate your metadata, validate and test, and debug with traces. Everything we’ll discuss here works today through the open-source Salesforce Skills Library and the Salesforce CLI.

Teach your coding agent Salesforce with Agent Skills

Agent Skills are how your coding assistant learns Salesforce. A skill is a small bundle of instructions and commands that teaches the assistant a specific task, such as building an Apex class or a Lightning web component (LWC), building a flow, or developing Agentforce agents. Without skills, the assistant guesses. With them, it runs the right steps and necessary CLI commands or MCP tools and follows conventions.

You should install these skills either globally or within your project directory for any coding agents besides Agentforce Vibes, as the latter includes them by default. The Salesforce Skills Library ships dozens of skills covering Apex, LWC, Agentforce, Data 360, and metadata deployment. 

Three skills drive the agent lifecycle specifically:

• developing-agentforce: Design, build, deploy, debug (see docs)
• testing-agentforce: Test specs and batch runs (see docs)
• observing-agentforce: Inspect production traces from Data 360 (see docs)

Once installed, in most coding agents you should be able to type ‘/’ in your assistant to browse them. You’ll see a skill load by name as the assistant works, for example, developing-agentforce activates the moment you ask for an agent scaffold.

You’ll also need a few common tools on your machine first: Node.js and the Salesforce CLI. And here’s the best part — if something is missing, use your assistant to get help. And if the assistant has permissions, it can also install these for you.

To install Salesforce Agent Skills, run the below command from your terminal or ask your assistant to run the below command.

npx skills add forcedotcom/sf-skills

After executing the command, you will navigate through a few quick configuration choices. First, you’ll pick the specific skills from the library to equip your assistant. Then, designate your preferred coding agent and decide if these instructions should be available across all your projects or just for the current local directory.

Scaffold the project and connect your org

Every Salesforce project starts with a scaffold — a folder holding all your metadata as files. This is the same project structure you already pull into an integrated development environment (IDE) like VS Code. Your assistant works against those local files, then deploys them to an org.

Here’s the shift that matters. You no longer memorize CLI flags or look up command syntax. You describe what you want in plain language, and the coding agent runs the right Salesforce CLI command for you. The CLI does the actual work — the agent just knows which command to call and translates your words into it.

For example, scaffolding a project used to mean typing the exact command and its flags:

sf project generate --name agent-script-demo

Now, you simply describe the goal in plain language, and the agent runs that command for you:

“Create a Salesforce project scaffold named agent-script-demo”

Keep each project in its own folder, so the agent only touches what it should. From there, the same pattern repeats for every step. For example, when you ask it to set up your org, the agent checks the current default and sets your scratch org or sandbox as the default for this project using the commands below.

sf config get target-org --json
sf config set target-org agent-build --json

You can also ask the coding agent to open your default org, and the coding agent will use the command below to open it.

sf org open

A best practice is to build in scratch orgs or sandboxes and never give your agent access to the production environment. Also, never paste secrets like passwords into a prompt. A handy workflow is to run a second terminal without the assistant. That way you can copy, edit, and run sensitive commands yourself. 

Design before you build

This is the most important habit in the whole lifecycle. If you let an agent build on its own, it may produce something you have to throw away. So, slow down and design first.

Two things make this easy. First, switch your assistant into plan mode (in Claude Code, press Shift+Tab to cycle to “plan mode”). In plan mode, the assistant proposes a plan instead of changing files. Second, ask the assistant to interview you before it builds. A prompt like this works well:

“Before you build anything, interview me to design this agent. Ask one question at a time and recommend a sensible default for each. Treat the design as a decision tree: when my answer opens new choices, follow that branch and keep asking until it’s fully resolved, then move to the next branch. Cover the data model, actions, permissions, and agent structure. Don’t stop or start building until every decision needed to build the agent is made.”

That single instruction turns the assistant into a design partner. It walks down every branch of the decision tree — following each answer to the sub-decisions it raises — and only stops once nothing is left to decide. Nothing gets built on a guess. For our example, an employee To-Do Manager agent, it walked through real architectural choices:

• Where should to-dos live: in a custom object, or the standard Task object?
• Which fields and status values does the agent need?
• Should the agent run as the logged-in user?
• Use one sub-agent with three flow actions, or a hub-and-spoke model with a sub-agent per task?
• Should the backing logic be Salesforce Flows or Apex?

Note that the above is an example prompt, and based on your organization’s best practices, you can build an agent skill of your own to help you design this, so you do not have to repeat this prompt.

The Claude Code coding assistant interviews the developer one question at a time, recommending a default for each design decision.

Visualizing your agent as a graph is helpful. Each sub-agent acts as a node representing a specific domain: a single, focused job with its own dedicated instructions and actions. A router node at the top orchestrates these sub-agents based on the conversation. Designing the agent means defining these nodes and providing clear instructions and tools to ensure that the agent achieves the user’s goals.

So, the rule of thumb is about domains, not difficulty. Keep a single sub-agent when the whole job lives in one domain, for example, frequently asked questions (FAQ) or a status lookup. Reach for multiple sub-agents in a hub-and-spoke shape when the work spans distinct domains that each deserve their own instructions, actions, or security gate. Most agents land at one to five domain sub-agents. You make these calls, not your coding agent. That’s the point — you end up more confident because you designed the graph.

The AI-generated info graphic below conveys these ideas.

Generate, deploy, and let the agent fix and retry

Once the plan is approved, the assistant builds everything: the custom object and fields, the flows, and the agent definition file written in Agent Script (the declarative format that specifies your agent’s sub-agents, routing logic, instructions, and action bindings). The output is an authoring bundle: the deployable package containing the agent’s complete definition as local metadata files. You can watch it happen live in VS Code as files appear.

Be sure to scope the work explicitly in your plan. A common choice is “build, deploy, and validate” before you publish. You can also add reminders that the assistant might otherwise skip, for instance, “make sure the new object has the right permissions; create a permission set.” Field-level security (FLS) and create-read-update-delete (CRUD) permissions matter, so call them out.

The standout behavior is an automated fix-and-retry loop. When a deploy fails, the assistant reads the compiler or deploy error, traces it to the offending metadata, applies a fix, and redeploys, repeating that cycle until the deploy succeeds. It’s the same edit-compile-debug loop you’d run by hand, just driven by the agent. If you want to go faster, you can fan out the work, so parallel agents build several flows at once instead of one after another. When you go for parallel work, make sure you understand dependencies and group them, so they can execute without stepping on each other.

You drive this in plain language: “Build a single sub-agent To-Do Manager using Salesforce Flows, build, deploy, and validate it, and create a permission set for the new object”. Behind that prompt, the developing-agentforce skill runs a precise sequence. It first generates the authoring bundle (the agent scaffold), then validates that Agent Script compiles with a local check, deploys the backing flows or Apex the actions reference, and finally deploys the authoring bundle itself. Knowing the sequence helps you follow along and step in when needed.

sf agent generate authoring-bundle --json --no-spec --name "To-Do Manager" --api-name To_Do_Manager
sf agent validate authoring-bundle --json --api-name To_Do_Manager
sf project deploy start --json --metadata Flow
sf project deploy start --json --metadata AiAuthoringBundle:To_Do_Manager

Notice two best practices baked into the skill. Every command leads with --json to make the output machine-readable, and every deploy names its metadata explicitly. A bare sf project deploy start ships everything that changed, and scoping each deploy keeps agent metadata from going out by accident.

Validate, then test in two modes

When the build finishes, the assistant validates the agent’s behavior paths automatically, checking far more paths than you’d test by hand. Validation is required before the agent can be published, so it’s built into the flow.

Still, don’t skip your own testing. Automated validation is a safety net, not a substitute for judgment. This is where the testing-agentforce skill comes in. It gives you two modes: quick smoke tests while you iterate, and a saved batch suite for regression testing and continuous integration. Use the first to move fast, and the second to keep the agent honest as it grows.

Quick smoke tests with preview sessions

The quick mode is a live preview session. You start a session, send a real utterance, and end the session when you’re done — each preview sends a trace you can read afterward. Note that --authoring-bundle must appear on all three subcommands.

sf agent preview start --json --authoring-bundle To_Do_Manager

sf agent preview send --json --authoring-bundle To_Do_Manager --session-id SESSION_ID --utterance "Create a to-do to write a blog"\

sf agent preview end --json --authoring-bundle To_Do_Manager --session-id SESSION_ID

Batch regression testing with test specs

For repeatable testing, you describe the cases you care about and the skill writes a test spec. The spec is a YAML file that lists each utterance alongside what should happen. Three assertions matter per case:

• expectedTopic: The sub-agent that the conversation should route to
• expectedActions: The actions that should fire
• expectedOutcome: A plain-language description of the right result

That last one is graded by a large language model (LLM) acting as a judge, so it reads the response the way a person would. It’s the most reliable assertion, so include it on every case.

name: To_Do_Manager_Tests
subjectType: AGENT
subjectName: To_Do_Manager
testCases:
  - utterance: "Create a to-do to write a blog"
    expectedTopic: To_Do_Management
    expectedActions:
      - Create_To_Do
    expectedOutcome: "A new to-do titled 'write a blog' is created and confirmed to the user."

You then create the test definition from that spec and run it as a batch, waiting for the results.

sf agent test create --json --spec specs/To_Do_Manager-testSpec.yaml --api-name To_Do_Manager_Tests --force-overwrite

sf agent test run --json --api-name To_Do_Manager_Tests --wait 10

When a case fails, the skill diagnoses it straight from the trace — a sub agent that didn’t match, an action that never fired, or an ungrounded response. It then applies a targeted fix and retries for a few iterations before asking for your help. You can also run the live preview in the new Agent Builder for an admin-friendly view, or use the Agentforce DX panel in VS Code to start a test session.

Note: We are enhancing the automated testing experience to support multi-turn conversation, injection of state variables, and verify action validations. Keep an eye on the release notes.

Publish and activate your agent

When it works, publish and activate the agent. Publishing turns the deployed bundle into a runnable agent version as Inactive; activating turns it on so users and tests can reach it. You can publish now and activate later if you prefer. Below are commands that the agent runs for publish and activation.

sf agent publish authoring-bundle --json --api-name To_Do_Manager
sf agent activate --json --api-name To_Do_Manager

And if you forgot a piece of metadata, just ask the agent to build it for you. The whole point is that you describe the gap and the assistant fills it. Maintain a repeatable history by committing your Agent Script and associated metadata to a source control system like Git. This practice ensures you can revert to a known functional version whenever necessary, keeping your development environment stable and secure.

Debug with traces, not guesswork

The agent trace is the primary debugging signal for Agentforce agents. It’s a JSON file generated after each conversation turn that shows which sub-agent handled the request, what the LLM received, and which actions fired. Agents rarely come out perfect on the first try, so you’ll keep tweaking them. You’ll work with traces in two places, and they look slightly different in each.

Local traces during development

While you build, the traces are local. After each preview send, the runtime writes one JSON file per conversation turn. Each trace shows the full execution path: which sub-agent handled the turn, what variables were set, what the LLM saw, and which actions it called. You’ll find these files in your project.

.sfdx/agents/To_Do_Manager/sessions//traces/.json

These local traces are instant and complete, but they only cover your own preview sessions. The fix loop is simple: open the trace, paste it back into your assistant, and explain what you expected versus what happened. In the Agent DX panel, you can grab the same trace with one click. The trace is detailed enough that the assistant usually pinpoints and fixes the issue — you can even ask it to “self-test using the trace and fix it.” This resolves the large majority of problems before the agent ever ships.

Production traces with the observing-agentforce skill

Once real users are on the agent, you need a different lens. That’s the job of the observing-agentforce skill. Instead of one local file, it queries the Session Trace Data Model (STDM) — the production session data that Agentforce stores in Data 360 — so you can see how the agent behaves across real conversations at volume.

The skill follows a three-step loop: observe, reproduce, improve. It queries production sessions to surface the failures that matter — sub-agent misroutes, action errors, low adherence, slow actions, and abandoned sessions. It then reproduces a suspect case in a local preview to confirm the root cause, and only then edits the agent to fix it. You ask in plain language, “find the worst-performing sessions from the last day and tell me why”, and the skill runs the queries and reads the results for you.

For either kind of trace, a visualizer helps when the routing itself is hard to follow. The agent is a graph: a router hands each conversation to a sub-agent, which builds variables and prompts, sends them to the LLM, and calls tools until it has an answer. A tool like AgentLens lets you walk that graph step by step, seeing each sub-agent handoff, the tools sent to the LLM, and the response that ends the flow.

Note: for agent observability at scale for production agents, it is recommended to set up dashboards and metrics using Agent Observability

Extend the lifecycle with custom agent skills

Adopt this lifecycle and your day-to-day changes. You stop clicking through Salesforce setup for routine work and start describing outcomes instead. When something isn’t right, the fix almost always lives in one of four places: your prompt, your context, the tools you built, or the skills you installed.

That last one is the real unlock. When a skill produces metadata you don’t like, improve the skill and contribute it back. Your fixes compound for everyone, and the assistant gets better at Salesforce over time. Pairing that with a design-first interview keeps you in control — you slow down just enough to learn and to own the design.

The agentic development lifecycle: Recap

The agentic development lifecycle gives you a faster, more reliable way to build Agentforce agents. Install Agent Skills from the Salesforce Skills Library so your assistant knows Salesforce, scaffold and connect your project, then design before you build with plan mode and a design-first interview. Let the assistant generate the metadata and fix-and-retry failed deployments, validate and test the result, and debug with traces when something’s off. You move quicker and stay the designer the entire time.

Want to go deeper or share what you’ve built? Join the conversation in the Salesforce Developers Trailblazer Community.

Resources

• Agentforce Developer Center
• Salesforce Skills Library on GitHub (forcedotcom/sf-skills)
• Agentforce DX Visual Studio Code extension

About the author

Mohith Shrivastava is a Principal Developer Advocate at Salesforce with 15 years of experience building enterprise-scale products on the Agentforce 360 Platform. Mohith is currently among the lead contributors on Salesforce Stack Exchange, a developer forum where Salesforce Developers can ask questions and share knowledge. You can follow him on LinkedIn.

The post Master the Agentic Development Lifecycle for Agentforce appeared first on Salesforce Developers Blog.

Of course, managed package triggers are a black box. We don’t own them, and we can’t touch them. But our custom triggers? That’s our house, and we get to set the rules. The answer isn’t more triggers. It’s one, done right.

That’s where Agentforce Vibes becomes your best pair programmer. It reads through your triggers, tells you exactly what each one is doing, spots the landmines, and helps you consolidate everything into a clean, scalable pattern iejggcbhdbklunjvfhejciflcuchnvrn the way it should have been built from the start. What would typically take days of manual code review and architectural planning gets done in a fraction of the time, so your team can focus on what actually matters building great solutions.

In my org, I had multiple triggers firing on the Opportunity object, each one written at a different point in time, by different developers, for different reasons. In this post, I’ll walk you through the approach I used to bring all of that chaos under one roof, into a single, clean trigger while intentionally leaving any managed package triggers untouched.

The workflows, skills, prompts, and steps you’ll see throughout this post are based on my own org, and your org will certainly look different. Your trigger count, logic complexity, and dependency map are uniquely yours. That’s completely normal, and honestly, that’s the point.

From concept to practice: Skills and workflows

What makes this approach powerful is that you can turn it into a reusable skill or workflow — a framework that you can run on any object, share across your team, or plug into other agents. The principles are universal; the execution is yours to shape.

Skills: Your on-demand code analyst

Think of a skill as a specialist you can call on instantly. Point it at your triggers and it surfaces what actually matters: recursion traps, SOQL inside loops, conflicting field assignments, or gaps in test coverage. Analysis that used to take hours of careful reading? It now takes minutes.

Workflows: Safe, repeatable refactoring at scale

A workflow takes that analysis and turns it into a structured, sequenced process: audit first, then refactor what needs fixing, then generate the consolidated trigger, handler, and tests in the right order. No steps skipped, no code merged before it’s ready. Just a clean, predictable path from messy to maintainable.

From chaos to a single, clean trigger

Below is the a generic workflow that I implemented to take multiple Apex triggers on a single object and consolidate them into one clean, maintainable handler.

This workflow works on any standard or custom object as it contains no hardcoded object names. You can run it multiple times on different objects. You’ll get the same process and the same quality of analysis without the need for reconfiguration.

Let’s take a look at the workflow steps in more detail.

Step 0: Project setup

Before you get started, there are a few things you’ll need in place.

This walkthrough assumes that you’re working in VS Code with the Salesforce Extension Pack installed, your org is authenticated via the Salesforce CLI, and the Salesforce DX MCP Server is enabled in Agentforce Vibes. If you’re already set up, feel free to skip ahead. Otherwise, each link above will get you there quickly.

I’ve published a base version of the skills and workflows for trigger consolidation on GitHub. Think of it as your ready-to-run starting point: fork it, adapt it to your org’s objects and conventions, and make it your own.

Now, let’s install the skills and workflows. Head over to this README for setup instructions, it walks you through copying the .a4drules/ directory into your Salesforce DX project root.

This copies three files into your project: apex-trigger-risk-scan.md, pex-trigger-consolidation-analysis.md, and trigger-consolidation.md.

your-sfdx-project/
├─ .a4drules/
│   ├─ skills/
│   │   └─ apex-trigger-risk-scan.md                  ← single trigger analysis skill
│   │      └─ apex-trigger-consolidation-analysis.md  ← cross trigger analysis skill
│   └─ workflows/
│       └─ trigger-consolidation.md    ← trigger consolidation workflow

That’s the entire install — no restart or configuration required. Agentforce Vibes picks up the new skills and workflow immediately.

Step 1: Workflow start

1. Click the Agentforce Vibes icon in the VS Code Activity Bar to open the chat panel.
2. Type the following command to start the trigger consolidation workflow.

   /trigger-consolidation
   

3. The workflow kicks off by asking which object to work on.

   Which Salesforce object do you want to consolidate triggers for?
   (e.g. Opportunity, Case, Account, Invoice__c)
   

4. Type an object name like Opportunity and press Enter.

Step 2: Metadata retrieval

The workflow uses the Salesforce CLI to query your org’s metadata to retrieve Apex triggers and the related helper classes.

You can watch it work in the chat panel with an output similar to this:

Running: sf data query --query "SELECT Name, ... FROM ApexTrigger
WHERE TableEnumOrId = 'Opportunity' AND Status = 'Active'"

## Summary of what was retrieved:
**Triggers (9 total, 5 readable):**
1. **OpportunityBefore** (x2) - Body hidden (managed package / org-installed, unreadable)
2. **OpportunityAfter** - Body hidden (unreadable)
3. **OpportunityTrigger** - Body hidden (unreadable)
4. **OppDeleteTrigger** - before delete — readable
5. **OppCreateTrigger** - before insert, after insert — readable
6. **OpportunityNotifyTrigger** - after insert, after update — readable
7. **OppStageTrigger** - before update — readable
8. **OpportunityUpdateTrigger** - before update, after update — readable
The dependent classes are all accessible: OpportunityUtils, OpportunityHelper, and NotificationService. No test classes exist for this trigger suite. Let me load the apex-trigger-analysis skill to conduct the risk assessment.

Step 3: Trigger analysis

With the source in hand, the workflow loads the two trigger analysis skills and runs every trigger through all risk dimensions.

Per-trigger scan: apex-trigger-risk-scan skill (seven dimensions)

Cross-trigger analysis: apex-trigger-consolidation-analysis skills (eight dimensions)

You’ll see findings stream into the panel in real time.

Score Meaning
1–3      Low — safe to consolidate with minimal prep
4–6      Medium — refactor required before merge
7–9      High — urgent action recommended
10       Critical — production incident likely without immediate action
Overall risk score: 7/10

Step 4: Plan creation

Here’s the part that matters: the workflow does not generate a single line of code yet.
Instead, it writes a detailed plan file to docs/trigger-audit-plan.md and pauses.

Audit complete. I've written the full plan to docs/trigger-audit-plan.md.
Overall risk score: 7/10
Please review the findings and edit anything before I generate
the consolidated scaffold.
When you're ready, reply YES to proceed. Reply NO to stop here.

Step 5: Plan review

Open the plan file in VS Code. It contains:

• Trigger inventory: Every trigger, its events, line count, risk score, and top finding
• Risk register: Every finding with severity, plain-English description, and recommendation
• Dependency graph: Which triggers share which helper classes, as a plain-text diagram
• Logic merge map: Exactly which logic from which trigger goes into each consolidated context, with conflicts flagged explicitly
• Best practices compliance: Where current triggers violate Apex standards and what the consolidated code will fix

This file is yours to edit. You can change the instructions, add team notes, remove a trigger from the plan, etc. When you’re ready to proceed, the workflow reads your edited version before it writes any code. What you see in the plan is what gets built.

When the plan looks right, go back to the Agentforce Vibes chat panel and type:

YES

Step 6: Plan execution

The workflow reads your (possibly edited) plan and generates consolidated files directly into your Salesforce DX project.

For instance, this is what you could see when consolidating an opportunity trigger:

✓ force-app/main/default/triggers/OpportunityTrigger.trigger        (28 lines)
✓ force-app/main/default/classes/OpportunityTriggerHandler.cls      (74 lines)
✓ force-app/main/default/classes/OpportunityTriggerHelper.cls       (32 lines)
✓ force-app/main/default/classes/OpportunityTriggerTest.cls         (58 lines)

Consolidation complete. Search for // CONFLICT and // ASYNC REQUIRED
comments — these are the only places that need manual review.

In this example, these four files are generated:

• OpportunityTrigger.trigger: This is a single trigger covering only the events that existed across the originals. No business logic in the body, everything delegates to the handler.
• OpportunityTriggerHandler.cls: One method per trigger context has a static Boolean recursion guard at the top, and every method is annotated with its consolidated source triggers. Logic is merged in the correct sequence per the Logic Merge Map you reviewed.
• OpportunityTriggerHelper.cls: This is the actual business logic, fully ported from the original triggers. All SOQL is bulkified outside loops, and duplicate logic from multiple triggers appears exactly once.
• OpportunityTriggerTest.cls: Test methods for single insert, bulk insert (200 records), update, bulk update, and delete are each traceable back to the source trigger.

Step 7: Manual review

Once the workflow terminates, the last manual task is to review the comments that were left during the execution. There are two types of comments that you should address:

• // CONFLICT: Where two triggers set the same field to different values. You decide which wins
• // ASYNC REQUIRED: Where a sync callout needs to move to @future or Queueable before deploying

Finally, the trigger jungle is a solved problem. Once a trigger is optimized, you can leverage prompts to deactivate the old trigger and, once tested and validated, promote the new implementation to a higher environment.

Considerations

• Before you adapt this framework, make it yours. The workflow and skill are starting points, not scripts. Your org’s complexity, naming conventions, and business logic are unique to everything generated here, so edit the audit plan before you commit to it.
• Spend real time in plan mode before generating any code. Open docs/trigger-audit-plan.md, work through the phases, flag the conflicts you already know about, and align the merge order with your team’s plan. The more thinking you do upfront, the cleaner the output.
• Treat generated code as a recommendation, not a final answer. Always review and validate before you deploy. These are smart suggestions, not certified production-ready commits.
• Fix High severity issues before you consolidate anything. If the audit surfaces recursion risks, SOQL or DML in loops, or field conflicts, stop and resolve those first. Merging broken logic into a single trigger doesn’t fix it and just makes it harder to debug later.
• Version control everything. This includes triggers, handler classes, service classes, audit files, test classes — all of it. If it gets generated or modified, it belongs in source control.
• Always test in a sandbox first and never run directly against production. The workflow connects to whichever org you’re authenticated to, so before running /trigger-consolidation, verify that sf org list shows a sandbox or scratch org as your default. Consolidating triggers in production without testing is how outages happen.
• Run one object at a time, but think about the whole org. This isn’t a one-and-done fix. Once Opportunity is clean, move to Case, then Account, then your custom objects. The phased approach is intentional: each consolidation builds confidence for the next.

Conclusion

Trigger sprawl is common and costly, and with the right approach, it’s completely solvable.

Ready to clean up your org? Start with your simplest triggers, follow the steps in this guide, build confidence, then tackle the high-traffic objects. Run the Agentforce Vibes analysis skill and let the audit canvas show you exactly what you’re dealing with. One trigger, one handler, zero surprises.

Resources

Agentforce Vibes

• Developer Guide: Agentforce Vibes Overview
• Developer Guide: Agentforce Vibes Quick Start
• Install: Salesforce Extension Pack for VS Code
• Documentation: Agentforce Vibes MCP Server 
• Developer Guide: Skills in Agentforce Vibes
• Developer Guide: Workflows in Agentforce Vibes

Salesforce CLI

• Setup Guide: Salesforce CLI 
• Command Reference: SF Project Retrieve
• Command Reference: SF Data Query 

Apex Trigger Best Practices

• Developer Guide: Apex Triggers 
• Developer Guide: Apex Best Practices
• Trailhead: Apex Trigger Badge

Metadata & Deployment

• Developer Guide: Metadata API 
• Reference: Package.xml Manifest
• Developer Guide: Custom Metadata Types 

About the author

Lakshmi Anusha Myneni is a Principal Technical Architect at Salesforce with 15 years of experience in the financial services industry. She partners closely with customers during the most critical stages of their journey, translating complex business challenges into compelling, technically sound Salesforce solutions.

The post Analyze and Consolidate Apex Triggers via Agentforce Vibes appeared first on Salesforce Developers Blog.

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.