salesforce

Overview

Build on the Salesforce platform — the world's largest CRM. This skill covers REST and Bulk API integration, SOQL/SOSL queries, Apex triggers and classes, Flow automation, Platform Events for real-time messaging, Connected Apps for OAuth2, Salesforce DX for source-driven development, and deployment pipelines. Suitable for CRM integrations, custom business logic, and extending Salesforce with external systems.

Instructions

Step 1: Authentication — Connected App & OAuth2

Create a Connected App (Setup → App Manager → New Connected App), enable OAuth, set scopes: api, refresh_token, full.

JWT Bearer Flow (server-to-server):

import jwt from "jsonwebtoken";
import fs from "fs";

async function getSalesforceToken(clientId: string, username: string) {
  const privateKey = fs.readFileSync("server.key", "utf-8");
  const token = jwt.sign({
    iss: clientId, sub: username, aud: "https://login.salesforce.com",
    exp: Math.floor(Date.now() / 1000) + 300,
  }, privateKey, { algorithm: "RS256" });

  const res = await fetch("https://login.salesforce.com/services/oauth2/token", {
    method: "POST", headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: new URLSearchParams({ grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer", assertion: token }),
  });
  const data = await res.json();
  return { accessToken: data.access_token, instanceUrl: data.instance_url };
}

API helper:

async function sf(method: string, path: string, token: string, instanceUrl: string, body?: any) {
  const res = await fetch(`${instanceUrl}/services/data/v60.0${path}`, {
    method,
    headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
    body: body ? JSON.stringify(body) : undefined,
  });
  if (!res.ok) throw new Error(`SF ${res.status}: ${await res.text()}`);
  return res.status === 204 ? null : res.json();
}

Step 2: SOQL & SOSL Queries

// Query with relationships
const opps = await sf("GET", `/query?q=${encodeURIComponent(`
  SELECT Id, Name, Amount, StageName, CloseDate, Account.Name, Owner.Name,
    (SELECT Id, Subject, Status FROM Tasks WHERE Status != 'Completed')
  FROM Opportunity WHERE StageName NOT IN ('Closed Won','Closed Lost') AND Amount > 50000
  ORDER BY CloseDate ASC`)}`, token, instanceUrl);

// Aggregate
const summary = await sf("GET", `/query?q=${encodeURIComponent(`
  SELECT StageName, COUNT(Id) cnt, SUM(Amount) total FROM Opportunity
  WHERE CloseDate = THIS_FISCAL_YEAR GROUP BY StageName`)}`, token, instanceUrl);

// Paginate large results
let url = `/query?q=${encodeURIComponent("SELECT Id, Name FROM Contact")}`;
const all = [];
while (url) {
  const data = await sf("GET", url, token, instanceUrl);
  all.push(...data.records);
  url = data.nextRecordsUrl || null;
}

// SOSL full-text search
const search = await sf("GET",
  `/search?q=${encodeURIComponent("FIND {TechStart} RETURNING Lead(Name,Email),Contact(Name),Account(Name)")}`,
  token, instanceUrl);

Step 3: REST API — CRUD & Composite

// Create Account + Contact + Opportunity
const account = await sf("POST", "/sobjects/Account", token, instanceUrl, {
  Name: "TechStart GmbH", Industry: "Technology", BillingCity: "Berlin", BillingCountry: "Germany",
});
await sf("POST", "/sobjects/Contact", token, instanceUrl, {
  FirstName: "Marta", LastName: "Schmidt", Email: "marta@techstart.io", AccountId: account.id, Title: "CTO",
});
await sf("POST", "/sobjects/Opportunity", token, instanceUrl, {
  Name: "TechStart — Enterprise License", AccountId: account.id,
  StageName: "Qualification", Amount: 150000, CloseDate: "2026-06-30",
});

// Update and upsert
await sf("PATCH", `/sobjects/Opportunity/${oppId}`, token, instanceUrl, { StageName: "Negotiation/Review", Amount: 175000 });
await sf("PATCH", `/sobjects/Account/External_ID__c/TECHSTART-001`, token, instanceUrl, { Name: "TechStart GmbH" });

// Composite API (up to 25 requests in one call)
await sf("POST", "/composite", token, instanceUrl, {
  allOrNone: true,
  compositeRequest: [
    { method: "POST", url: "/services/data/v60.0/sobjects/Account", referenceId: "newAccount", body: { Name: "NewCo" } },
    { method: "POST", url: "/services/data/v60.0/sobjects/Contact", referenceId: "newContact",
      body: { LastName: "Doe", AccountId: "@{newAccount.id}" } },
  ],
});

Step 4: Bulk API 2.0

const job = await sf("POST", "/jobs/ingest", token, instanceUrl, {
  object: "Contact", operation: "upsert", externalIdFieldName: "Email", contentType: "CSV",
});
await fetch(`${instanceUrl}/services/data/v60.0/jobs/ingest/${job.id}/batches`, {
  method: "PUT",
  headers: { Authorization: `Bearer ${token}`, "Content-Type": "text/csv" },
  body: `FirstName,LastName,Email,AccountId\nMarta,Schmidt,marta@techstart.io,${accountId}`,
});
await sf("PATCH", `/jobs/ingest/${job.id}`, token, instanceUrl, { state: "UploadComplete" });

Step 5: Apex & Platform Events

Trigger (auto-task on high-value opportunities):

trigger OpportunityTrigger on Opportunity (after insert) {
    List<Task> tasks = new List<Task>();
    for (Opportunity opp : Trigger.new) {
        if (opp.Amount >= 100000) {
            tasks.add(new Task(Subject='Review: ' + opp.Name, WhatId=opp.Id,
                OwnerId=opp.OwnerId, ActivityDate=Date.today().addDays(3), Priority='High'));
        }
    }
    if (!tasks.isEmpty()) insert tasks;
}

Custom REST endpoint:

@RestResource(urlMapping='/custom/deals/*')
global class DealAPI {
    @HttpGet
    global static Map<String, Object> getActiveDealsSummary() {
        AggregateResult[] results = [SELECT StageName, COUNT(Id) cnt, SUM(Amount) total
            FROM Opportunity WHERE IsClosed = false GROUP BY StageName];
        List<Map<String, Object>> stages = new List<Map<String, Object>>();
        for (AggregateResult ar : results)
            stages.add(new Map<String, Object>{'stage'=>ar.get('StageName'),'count'=>ar.get('cnt'),'total'=>ar.get('total')});
        return new Map<String, Object>{'stages'=>stages, 'generatedAt'=>Datetime.now()};
    }
}

Platform Events — define Deal_Closed__e with fields in Setup, publish from Apex with EventBus.publish(event), subscribe externally via CometD Streaming API.

Step 6: SFDX & CI/CD

sf project generate --name my-project && cd my-project
sf org login web --alias myorg
sf project retrieve start --target-org myorg
sf project deploy start --source-dir force-app --target-org myorg
sf apex test run --target-org myorg --code-coverage --result-format human

GitHub Actions deploy:

steps:
  - uses: actions/checkout@v4
  - run: npm install -g @salesforce/cli
  - run: echo "${{ secrets.SF_AUTH_URL }}" > auth.txt && sf org login sfdx-url --sfdx-url-file auth.txt --alias prod
  - run: sf project deploy start --source-dir force-app --target-org prod --test-level RunLocalTests

Step 7: Integration Patterns

Change Data Capture (SF → external):

client.subscribe("/data/OpportunityChangeEvent", async (event: any) => {
  const { changeType, recordIds } = event.payload.ChangeEventHeader;
  if (changeType === "UPDATE" || changeType === "CREATE") {
    for (const id of recordIds) {
      const record = await sf("GET", `/sobjects/Opportunity/${id}`, token, instanceUrl);
      await externalDb.upsert("opportunities", { sf_id: id, name: record.Name, amount: record.Amount, stage: record.StageName });
    }
  }
});

External webhook → Salesforce (Stripe example):

app.post("/webhook/stripe", async (req, res) => {
  if (req.body.type === "payment_intent.succeeded") {
    const payment = req.body.data.object;
    const opp = await sf("GET",
      `/query?q=${encodeURIComponent(`SELECT Id FROM Opportunity WHERE Stripe_Payment_ID__c = '${payment.id}'`)}`,
      token, instanceUrl);
    if (opp.records.length > 0) {
      await sf("PATCH", `/sobjects/Opportunity/${opp.records[0].Id}`, token, instanceUrl, { StageName: "Closed Won" });
    }
  }
  res.sendStatus(200);
});

Examples

Example 1: Lead-to-deal pipeline with automated follow-ups

User prompt: "Create an Apex trigger that auto-creates a follow-up task when a new opportunity over $100K is created, and write a SOQL query that gives me a pipeline summary grouped by stage with total amounts for this fiscal year."

The agent will write an after insert Apex trigger on Opportunity that checks Amount >= 100000 and creates a Task with 3-day due date, high priority, and the opportunity owner as assignee. It will also build a SOQL aggregate query using GROUP BY StageName with COUNT(Id) and SUM(Amount) filtered to THIS_FISCAL_YEAR, and show how to call it via the REST API to get the pipeline summary.

Example 2: Bi-directional sync between Salesforce and an external order system

User prompt: "Set up Change Data Capture to sync closed-won opportunities to our PostgreSQL database in real time, and create an inbound webhook endpoint that updates Salesforce opportunities when Stripe payments succeed."

The agent will subscribe to /data/OpportunityChangeEvent via CometD, filter for UPDATE events where StageName changed to "Closed Won", fetch the full record, and upsert it into PostgreSQL. For the inbound flow, it will create an Express endpoint at /webhook/stripe that extracts the payment ID from the Stripe event, queries Salesforce for the matching opportunity by custom field Stripe_Payment_ID__c, and patches the stage to "Closed Won" with the payment date.

Guidelines

• Use the Composite API for related record creation — creating an Account, Contact, and Opportunity in a single composite call with @{referenceId.id} references is faster and ensures atomicity with allOrNone: true.
• Paginate all SOQL queries — results over 2,000 records return a nextRecordsUrl; always loop until it is null to avoid silently missing data.
• Prefer Bulk API 2.0 for large data loads — anything over a few hundred records should use the Bulk API with CSV upload to avoid governor limits and API call quotas.
• Always test Apex with RunLocalTests — Salesforce requires 75% code coverage for production deploys; run sf apex test run before every deployment to catch failures early.
• Sanitize SOQL inputs — never interpolate user input directly into SOQL strings; use bind variables in Apex or parameterize queries to prevent SOQL injection.
• Handle CSRF tokens for on-premise S/4HANA — write operations against on-premise Salesforce instances may require fetching an X-CSRF-Token header first; cloud instances using OAuth2 do not need this.