Skip to content

forcedotcom/sf-skills / plugins/builder/salesforce-development/skills/platform-data-manage

platform-data-manage

Verified

Salesforce data operations with 130-point scoring. Use to create, update, delete, bulk import/export, generate test data, and clean up org records via sf CLI and anonymous Apex. TRIGGER on creating test data, bulk import/export, sf data CLI commands, data-factory patterns for Apex tests, or seeding/cleaning org records. DO NOT TRIGGER for SOQL query writing only (use platform-soql-query), Apex test execution (use platform-apex-test-run), or metadata deployment (use platform-metadata-deploy).

FileKindSize
README.mdmarkdown4.5 KB
SKILL.mdskill md10.5 KB
assets/bulk/bulk-insert-10000.apexother12.3 KB
assets/bulk/bulk-insert-200.apexother12.4 KB
assets/bulk/bulk-insert-500.apexother13.1 KB
assets/bulk/bulk-upsert-external-id.apexother13.4 KB
assets/cleanup/delete-by-created-date.apexother15.9 KB
assets/cleanup/delete-by-name.apexother12.9 KB
assets/cleanup/delete-test-data.apexother16.6 KB
assets/cleanup/rollback-transaction.apexother12.4 KB
assets/csv/account-import.csvother1.8 KB
assets/csv/contact-import.csvother1.9 KB
assets/csv/custom-object-import.csvother1.1 KB
assets/csv/opportunity-import.csvother1.6 KB
assets/factories/account-factory.apexother5.6 KB
assets/factories/case-factory.apexother8.1 KB
assets/factories/contact-factory.apexother5.9 KB
assets/factories/custom-object-factory.apexother10.8 KB
assets/factories/event-factory.apexother9.6 KB
assets/factories/hierarchy-factory.apexother16.0 KB
assets/factories/lead-factory.apexother6.4 KB
assets/factories/opportunity-factory.apexother7.3 KB
assets/factories/task-factory.apexother8.1 KB
assets/factories/user-factory.apexother8.8 KB
assets/json/account-contact-tree.jsonconfig3.6 KB
assets/json/account-opportunity-tree.jsonconfig3.3 KB
assets/json/full-hierarchy-tree.jsonconfig5.8 KB
assets/soql/aggregate.soqlother12.3 KB
assets/soql/child-to-parent.soqlother9.8 KB
assets/soql/parent-to-child.soqlother8.6 KB
assets/soql/polymorphic.soqlother11.1 KB
assets/soql/subquery.soqlother16.2 KB
references/anonymous-apex-guide.mdmarkdown2.0 KB
references/bulk-operations-guide.mdmarkdown1.8 KB
references/bulk-testing-example.mdmarkdown4.9 KB
references/cleanup-rollback-example.mdmarkdown8.2 KB
references/cleanup-rollback-guide.mdmarkdown1.7 KB
references/crud-workflow-example.mdmarkdown4.0 KB
references/governor-limits-reference.mdmarkdown1.8 KB
references/orchestration.mdmarkdown7.0 KB
references/relationship-query-examples.mdmarkdown5.7 KB
references/sf-cli-data-commands.mdmarkdown2.8 KB
references/soql-relationship-guide.mdmarkdown2.0 KB
references/test-data-best-practices.mdmarkdown3.2 KB
references/test-data-factory-usage.mdmarkdown7.6 KB
references/test-data-patterns.mdmarkdown2.4 KB
scripts/soql_validator.pyscript10.9 KB
scripts/validate_data_operation.pyscript13.5 KB

assets/bulk/bulk-upsert-external-id.apex

View on GitHub
/**
 * ═══════════════════════════════════════════════════════════════════════════════
 * BULK UPSERT WITH EXTERNAL ID
 * For data synchronization and migration scenarios
 * ═══════════════════════════════════════════════════════════════════════════════
 *
 * PURPOSE:
 * Upsert (insert or update) records using an External ID field.
 * This is essential for:
 * • Data synchronization with external systems
 * • Data migration from legacy systems
 * • Ongoing integrations where records may or may not exist
 *
 * HOW IT WORKS:
 * • If External ID matches → UPDATE existing record
 * • If External ID not found → INSERT new record
 * • External ID field must be marked as "External ID" in Salesforce
 *
 * ═══════════════════════════════════════════════════════════════════════════════
 */

// ═══════════════════════════════════════════════════════════════════════════════
// APEX UPSERT EXAMPLE
// ═══════════════════════════════════════════════════════════════════════════════

/**
 * Example: Upsert Accounts using External_Id__c field
 *
 * Prerequisites:
 * 1. Create a custom field on Account: External_Id__c (Text, External ID, Unique)
 * 2. Ensure field is marked as "External ID" in field settings
 */

// Sample data simulating external system records
List<Map<String, Object>> externalData = new List<Map<String, Object>>{
    new Map<String, Object>{
        'externalId' => 'EXT-001',
        'name' => 'External Account One',
        'industry' => 'Technology',
        'revenue' => 1000000
    },
    new Map<String, Object>{
        'externalId' => 'EXT-002',
        'name' => 'External Account Two',
        'industry' => 'Healthcare',
        'revenue' => 2000000
    },
    new Map<String, Object>{
        'externalId' => 'EXT-003',
        'name' => 'External Account Three',
        'industry' => 'Finance',
        'revenue' => 3000000
    }
};

// Build Account records with External ID
List<Account> accountsToUpsert = new List<Account>();

for (Map<String, Object> data : externalData) {
    accountsToUpsert.add(new Account(
        External_Id__c = (String) data.get('externalId'),
        Name = (String) data.get('name'),
        Industry = (String) data.get('industry'),
        AnnualRevenue = (Decimal) data.get('revenue'),
        Type = 'Prospect',
        Description = 'Synced from external system'
    ));
}

// Upsert using External ID field
Schema.SObjectField externalIdField = Account.External_Id__c;
List<Database.UpsertResult> results = Database.upsert(accountsToUpsert, externalIdField, false);

// Process results
Integer insertedCount = 0;
Integer updatedCount = 0;
Integer errorCount = 0;

for (Integer i = 0; i < results.size(); i++) {
    Database.UpsertResult result = results[i];
    Account acc = accountsToUpsert[i];

    if (result.isSuccess()) {
        if (result.isCreated()) {
            insertedCount++;
            System.debug('✓ INSERTED: ' + acc.External_Id__c + ' -> ' + result.getId());
        } else {
            updatedCount++;
            System.debug('✓ UPDATED: ' + acc.External_Id__c + ' -> ' + result.getId());
        }
    } else {
        errorCount++;
        for (Database.Error err : result.getErrors()) {
            System.debug('✗ ERROR: ' + acc.External_Id__c + ' -> ' + err.getMessage());
        }
    }
}

System.debug('');
System.debug('═══════════════════════════════════════════════════════════════');
System.debug('UPSERT COMPLETE');
System.debug('═══════════════════════════════════════════════════════════════');
System.debug('Inserted: ' + insertedCount);
System.debug('Updated: ' + updatedCount);
System.debug('Errors: ' + errorCount);
System.debug('═══════════════════════════════════════════════════════════════');

// ═══════════════════════════════════════════════════════════════════════════════
// SF CLI BULK UPSERT
// ═══════════════════════════════════════════════════════════════════════════════

/*
STEP 1: Create CSV with External ID column

Example accounts-upsert.csv:
External_Id__c,Name,Industry,Type,AnnualRevenue,BillingCity,BillingState
EXT-001,External Account One,Technology,Prospect,1000000,San Francisco,CA
EXT-002,External Account Two,Healthcare,Customer,2000000,New York,NY
EXT-003,External Account Three,Finance,Partner,3000000,Chicago,IL

STEP 2: Run bulk upsert

sf data upsert bulk \
  --file accounts-upsert.csv \
  --sobject Account \
  --external-id External_Id__c \
  --target-org myorg \
  --wait 30

NOTES:
• The External_Id__c field must exist and be marked as External ID in Salesforce
• To use standard Id field as the external ID: --external-id Id
• CSV must include the external ID column
*/

// ═══════════════════════════════════════════════════════════════════════════════
// EXAMPLE: UPSERT CONTACTS WITH ACCOUNT RELATIONSHIP
// ═══════════════════════════════════════════════════════════════════════════════

/**
 * Upsert Contacts and establish Account relationship via External ID
 *
 * Prerequisites:
 * 1. Account.External_Id__c exists and has values
 * 2. Contact.External_Id__c exists
 */

/*
List<Contact> contactsToUpsert = new List<Contact>();

// Create Contacts referencing Accounts by External ID
for (Map<String, Object> data : externalContactData) {
    Contact con = new Contact(
        External_Id__c = (String) data.get('contactExternalId'),
        FirstName = (String) data.get('firstName'),
        LastName = (String) data.get('lastName'),
        Email = (String) data.get('email')
    );

    // Set Account relationship via External ID
    // This creates the relationship without querying for the Account first
    con.Account = new Account(
        External_Id__c = (String) data.get('accountExternalId')
    );

    contactsToUpsert.add(con);
}

// Upsert Contacts
Database.upsert(contactsToUpsert, Contact.External_Id__c, false);
*/

// ═══════════════════════════════════════════════════════════════════════════════
// CSV FOR CONTACT UPSERT WITH ACCOUNT RELATIONSHIP
// ═══════════════════════════════════════════════════════════════════════════════

/*
Example contacts-upsert.csv:

External_Id__c,FirstName,LastName,Email,Account.External_Id__c
CON-001,John,Smith,john.smith@example.com,EXT-001
CON-002,Jane,Doe,jane.doe@example.com,EXT-001
CON-003,Bob,Johnson,bob.johnson@example.com,EXT-002

Note: Use "Account.External_Id__c" to reference parent by External ID

sf data upsert bulk \
  --file contacts-upsert.csv \
  --sobject Contact \
  --external-id External_Id__c \
  --target-org myorg \
  --wait 30
*/

// ═══════════════════════════════════════════════════════════════════════════════
// EXAMPLE: UPSERT WITH STANDARD ID (Update existing records)
// ═══════════════════════════════════════════════════════════════════════════════

/*
When you have Salesforce IDs (from export), use Id as the external ID:

Example updates.csv:
Id,Name,Industry,AnnualRevenue
001XXXXXXXXXXXX1,Updated Account One,Technology,1500000
001XXXXXXXXXXXX2,Updated Account Two,Healthcare,2500000

sf data upsert bulk \
  --file updates.csv \
  --sobject Account \
  --external-id Id \
  --target-org myorg \
  --wait 30
*/

// ═══════════════════════════════════════════════════════════════════════════════
// COMPLETE SYNC WORKFLOW EXAMPLE
// ═══════════════════════════════════════════════════════════════════════════════

/*
FULL SYNC WORKFLOW:

1. Export current data from Salesforce
   sf data query \
     --query "SELECT External_Id__c, Name, Industry FROM Account WHERE External_Id__c != null" \
     --target-org myorg \
     --result-format csv \
     > current-accounts.csv

2. Generate sync file from external system (your process)
   - Include External_Id__c for each record
   - Include all fields to update/insert

3. Upsert the sync file
   sf data upsert bulk \
     --file sync-accounts.csv \
     --sobject Account \
     --external-id External_Id__c \
     --target-org myorg \
     --wait 30

4. Check results
   sf data bulk results \
     --job-id [job-id-from-step-3] \
     --target-org myorg
*/

// ═══════════════════════════════════════════════════════════════════════════════
// BATCH APEX FOR COMPLEX UPSERT LOGIC
// ═══════════════════════════════════════════════════════════════════════════════

/**
 * Batch class for upserting with custom logic
 */
public class BulkUpsertProcessor implements Database.Batchable<SObject>, Database.Stateful {

    private String query;
    private Integer insertedCount = 0;
    private Integer updatedCount = 0;
    private Integer errorCount = 0;

    public BulkUpsertProcessor(String soqlQuery) {
        this.query = soqlQuery;
    }

    public Database.QueryLocator start(Database.BatchableContext bc) {
        return Database.getQueryLocator(query);
    }

    public void execute(Database.BatchableContext bc, List<SObject> records) {
        // Transform and prepare records for upsert
        List<Account> accountsToUpsert = new List<Account>();

        for (SObject record : records) {
            Account source = (Account) record;

            // Create upsert record
            Account target = new Account(
                External_Id__c = source.External_Id__c,
                Name = source.Name,
                Industry = source.Industry,
                AnnualRevenue = source.AnnualRevenue,
                LastModifiedDate = DateTime.now() // Will be auto-updated
            );

            // Apply transformation logic
            if (target.AnnualRevenue != null && target.AnnualRevenue > 1000000) {
                target.Type = 'Enterprise';
            }

            accountsToUpsert.add(target);
        }

        // Upsert with partial success
        List<Database.UpsertResult> results = Database.upsert(
            accountsToUpsert,
            Account.External_Id__c,
            false // Allow partial success
        );

        // Track results
        for (Database.UpsertResult result : results) {
            if (result.isSuccess()) {
                if (result.isCreated()) {
                    insertedCount++;
                } else {
                    updatedCount++;
                }
            } else {
                errorCount++;
            }
        }
    }

    public void finish(Database.BatchableContext bc) {
        System.debug('Batch Upsert Complete:');
        System.debug('  Inserted: ' + insertedCount);
        System.debug('  Updated: ' + updatedCount);
        System.debug('  Errors: ' + errorCount);
    }
}

// Execute with:
// String query = 'SELECT External_Id__c, Name, Industry, AnnualRevenue FROM Account WHERE External_Id__c != null';
// Database.executeBatch(new BulkUpsertProcessor(query), 200);
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall