@raishin/vanguard-frontier-agentic 2.3.0 → 2.5.0

package/skills/salesforce/salesforce-bulk-data-ops-skill/references/anonymous-apex-patterns.md

@@ -0,0 +1,380 @@
+# Anonymous Apex Patterns Reference
+
+## Core Safety Rules
+
+Every Anonymous Apex bulk script must follow these rules:
+
+1. **Never DML inside a loop** — collect records, DML after loop
+2. **allOrNone=false** — partial success; never block all on one failure
+3. **Database.SaveResult[] iteration** — log every failure
+4. **Chunk to 200** — Apex DML batch limit per transaction
+5. **SOQL in query phase only** — no SOQL inside loops
+6. **Governor limit estimation** — comment the expected row count
+
+---
+
+## Pattern 1: Mass Owner Reassignment
+
+```apex
+/**
+ * Mass Owner Reassignment
+ * Target: Opportunity records owned by the source user
+ * Volume: Estimate <n> records
+ * Run in: SANDBOX FIRST. Route to salesforce-live-guard-agent for production.
+ */
+
+// CONFIGURE THESE VALUES
+String sourceUsername = 'outbound_rep@company.com';
+String targetUsername = 'new_owner@company.com';
+Integer BATCH_SIZE = 200;
+
+// Resolve user IDs dynamically — do not hardcode
+Id sourceOwnerId = [SELECT Id FROM User WHERE Username = :sourceUsername LIMIT 1].Id;
+Id targetOwnerId = [SELECT Id FROM User WHERE Username = :targetUsername LIMIT 1].Id;
+
+System.debug('Source Owner: ' + sourceOwnerId);
+System.debug('Target Owner: ' + targetOwnerId);
+
+// Query affected records
+List<Opportunity> oppsToUpdate = [
+    SELECT Id, OwnerId, Name
+    FROM Opportunity
+    WHERE OwnerId = :sourceOwnerId
+    AND IsClosed = false
+    ORDER BY Id
+    LIMIT 10000
+];
+
+System.debug('Records to update: ' + oppsToUpdate.size);
+
+// Update in chunks
+Integer successCount = 0;
+Integer failCount = 0;
+
+for (Integer i = 0; i < oppsToUpdate.size; i += BATCH_SIZE) {
+    Integer endIdx = Math.min(i + BATCH_SIZE, oppsToUpdate.size);
+    List<Opportunity> batch = new List<Opportunity>;
+    for (Integer j = i; j < endIdx; j++) {
+        batch.add(new Opportunity(
+            Id = oppsToUpdate[j].Id,
+            OwnerId = targetOwnerId
+        ));
+    }
+    Database.SaveResult[] results = Database.update(batch, false);
+    for (Database.SaveResult sr : results) {
+        if (sr.isSuccess) {
+            successCount++;
+        } else {
+            failCount++;
+            System.debug('ERROR on record ' + sr.getId +
+                ': ' + sr.getErrors[0].getMessage);
+        }
+    }
+}
+
+System.debug('Reassignment complete. Success: ' + successCount + ' | Failed: ' + failCount);
+```
+
+---
+
+## Pattern 2: Mass Field Update
+
+```apex
+/**
+ * Mass Field Update — set a field value on a filtered set of records
+ * Target: Account records missing Industry classification
+ * Volume: Estimate <n> records
+ * Run in: SANDBOX FIRST.
+ */
+
+Integer BATCH_SIZE = 200;
+
+// Query affected records
+List<Account> accountsToUpdate = [
+    SELECT Id, Name, Industry
+    FROM Account
+    WHERE Industry = null
+    AND BillingCountry = 'United States'
+    AND Type = 'Customer - Direct'
+    ORDER BY Id
+    LIMIT 10000
+];
+
+System.debug('Records to update: ' + accountsToUpdate.size);
+
+Integer successCount = 0;
+Integer failCount = 0;
+
+for (Integer i = 0; i < accountsToUpdate.size; i += BATCH_SIZE) {
+    Integer endIdx = Math.min(i + BATCH_SIZE, accountsToUpdate.size);
+    List<Account> batch = new List<Account>;
+    for (Integer j = i; j < endIdx; j++) {
+        batch.add(new Account(
+            Id = accountsToUpdate[j].Id,
+            Industry = 'Other'  // CONFIGURE: set correct default value
+        ));
+    }
+    Database.SaveResult[] results = Database.update(batch, false);
+    for (Database.SaveResult sr : results) {
+        if (sr.isSuccess) {
+            successCount++;
+        } else {
+            failCount++;
+            System.debug('ERROR: ' + sr.getId + ' | ' + sr.getErrors[0].getMessage);
+        }
+    }
+}
+
+System.debug('Update complete. Success: ' + successCount + ' | Failed: ' + failCount);
+```
+
+---
+
+## Pattern 3: Batch Close Stale Opportunities
+
+```apex
+/**
+ * Batch Close Stale Opportunities
+ * Target: Open Opportunities with CloseDate > 90 days ago
+ * Effect: Sets Stage to Closed Lost and adds a note
+ * Run in: SANDBOX FIRST.
+ */
+
+Integer BATCH_SIZE = 200;
+Integer STALE_DAYS = 90;  // CONFIGURE: number of days past close date
+
+Date staleDate = Date.today.addDays(-STALE_DAYS);
+
+List<Opportunity> staleOpps = [
+    SELECT Id, Name, StageName, CloseDate, OwnerId
+    FROM Opportunity
+    WHERE IsClosed = false
+    AND CloseDate < :staleDate
+    ORDER BY CloseDate ASC
+    LIMIT 10000
+];
+
+System.debug('Stale opportunities to close: ' + staleOpps.size);
+
+Integer successCount = 0;
+Integer failCount = 0;
+
+for (Integer i = 0; i < staleOpps.size; i += BATCH_SIZE) {
+    Integer endIdx = Math.min(i + BATCH_SIZE, staleOpps.size);
+    List<Opportunity> batch = new List<Opportunity>;
+    for (Integer j = i; j < endIdx; j++) {
+        batch.add(new Opportunity(
+            Id = staleOpps[j].Id,
+            StageName = 'Closed Lost',  // CONFIGURE: target stage
+            Description = 'Auto-closed by bulk ops script on ' + Date.today.format +
+                          '. Original close date: ' + staleOpps[j].CloseDate.format,
+            CloseDate = Date.today  // Required if validation rule checks CloseDate
+        ));
+    }
+    Database.SaveResult[] results = Database.update(batch, false);
+    for (Database.SaveResult sr : results) {
+        if (sr.isSuccess) {
+            successCount++;
+        } else {
+            failCount++;
+            System.debug('ERROR: ' + sr.getId + ' | ' + sr.getErrors[0].getMessage);
+        }
+    }
+}
+
+System.debug('Close complete. Success: ' + successCount + ' | Failed: ' + failCount);
+```
+
+---
+
+## Pattern 4: Contact Deactivation (Soft)
+
+```apex
+/**
+ * Contact Deactivation
+ * Target: Contacts with no activity in the past 365 days
+ * Effect: Sets HasOptedOutOfEmail=true and a custom Active__c flag to false
+ * NOTE: This does NOT delete contacts. Soft deactivation only.
+ * Run in: SANDBOX FIRST.
+ */
+
+Integer BATCH_SIZE = 200;
+Date inactivityThreshold = Date.today.addDays(-365);
+
+List<Contact> inactiveContacts = [
+    SELECT Id, Name, Email, LastActivityDate
+    FROM Contact
+    WHERE LastActivityDate < :inactivityThreshold
+    AND HasOptedOutOfEmail = false
+    // AND Active__c = true  // CONFIGURE: uncomment if you have an Active field
+    LIMIT 10000
+];
+
+System.debug('Contacts to deactivate: ' + inactiveContacts.size);
+
+Integer successCount = 0;
+Integer failCount = 0;
+
+for (Integer i = 0; i < inactiveContacts.size; i += BATCH_SIZE) {
+    Integer endIdx = Math.min(i + BATCH_SIZE, inactiveContacts.size);
+    List<Contact> batch = new List<Contact>;
+    for (Integer j = i; j < endIdx; j++) {
+        batch.add(new Contact(
+            Id = inactiveContacts[j].Id,
+            HasOptedOutOfEmail = true
+            // Active__c = false  // CONFIGURE: uncomment if field exists
+        ));
+    }
+    Database.SaveResult[] results = Database.update(batch, false);
+    for (Database.SaveResult sr : results) {
+        if (sr.isSuccess) {
+            successCount++;
+        } else {
+            failCount++;
+            System.debug('ERROR: ' + sr.getId + ' | ' + sr.getErrors[0].getMessage);
+        }
+    }
+}
+
+System.debug('Deactivation complete. Success: ' + successCount + ' | Failed: ' + failCount);
+```
+
+---
+
+## Pattern 5: Duplicate Lead Merge (MergeLeads Pattern)
+
+```apex
+/**
+ * Merge Duplicate Leads by Email
+ * Merges duplicate leads keeping the oldest record as master
+ * Limit: Database.merge supports max 2 duplicates per master call
+ * Run in: SANDBOX FIRST. Merged records are NOT recoverable from Recycle Bin.
+ */
+
+Integer MERGE_BATCH_LIMIT = 200;  // Number of merges per run
+
+// Find duplicate emails (requires pre-queried duplicate map — see notes)
+// IMPORTANT: Build duplicate map outside script from a Data Loader export
+// This example uses a hardcoded map for illustration
+Map<String, List<Id>> duplicateMap = new Map<String, List<Id>>{
+    // 'email@example.com' => [masterLeadId, duplicateLeadId1, duplicateLeadId2]
+    // POPULATE from SOQL query or Data Loader export
+};
+
+// QUERY APPROACH (use when volume is manageable):
+List<AggregateResult> dupeGroups = [
+    SELECT Email, COUNT(Id) cnt, MIN(Id) masterId
+    FROM Lead
+    WHERE IsConverted = false
+    AND Email != null
+    GROUP BY Email
+    HAVING COUNT(Id) > 1
+    LIMIT :MERGE_BATCH_LIMIT
+];
+
+Integer mergeCount = 0;
+Integer errorCount = 0;
+
+for (AggregateResult ar : dupeGroups) {
+    String email = (String) ar.get('Email');
+    Id masterId = (Id) ar.get('masterId');
+
+    List<Lead> dupes = [
+        SELECT Id FROM Lead
+        WHERE Email = :email
+        AND Id != :masterId
+        AND IsConverted = false
+        LIMIT 2  // Database.merge supports max 2 duplicates per call
+    ];
+
+    if (!dupes.isEmpty) {
+        try {
+            Database.merge(new Lead(Id = masterId), dupes, false);
+            mergeCount++;
+        } catch (Exception e) {
+            errorCount++;
+            System.debug('Merge failed for master ' + masterId + ': ' + e.getMessage);
+        }
+    }
+}
+
+System.debug('Merges complete. Success: ' + mergeCount + ' | Failed: ' + errorCount);
+```
+
+**Important notes on merge:**
+- `Database.merge` is NOT reversible — merged records are permanently combined
+- Maximum 2 duplicate records per merge call
+- Always run in sandbox first and verify the master selection logic
+
+---
+
+## Pattern 6: Lead Conversion
+
+```apex
+/**
+ * Lead Conversion
+ * Converts qualified leads to Contact + Account + Opportunity
+ * Run in: SANDBOX FIRST.
+ */
+
+Integer BATCH_SIZE = 50;  // Lead conversion is more expensive — use smaller batch
+
+List<Lead> leadsToConvert = [
+    SELECT Id, FirstName, LastName, Company, Email, Status
+    FROM Lead
+    WHERE IsConverted = false
+    AND Status = 'Qualified'  // CONFIGURE: your qualified status value
+    LIMIT 200
+];
+
+System.debug('Leads to convert: ' + leadsToConvert.size);
+
+List<Database.LeadConvert> conversions = new List<Database.LeadConvert>;
+LeadStatus convertedStatus = [
+    SELECT MasterLabel FROM LeadStatus WHERE IsConverted = true LIMIT 1
+];
+
+for (Lead l : leadsToConvert) {
+    Database.LeadConvert lc = new Database.LeadConvert;
+    lc.setLeadId(l.Id);
+    lc.setConvertedStatus(convertedStatus.MasterLabel);
+    lc.setDoNotCreateOpportunity(false);  // CONFIGURE: set true to skip Opp creation
+    lc.setOverwriteLeadSource(false);
+    conversions.add(lc);
+}
+
+Database.LeadConvertResult[] results = Database.convertLead(conversions, false);
+Integer successCount = 0;
+Integer failCount = 0;
+
+for (Database.LeadConvertResult lcr : results) {
+    if (lcr.isSuccess) {
+        successCount++;
+        System.debug('Converted: Lead ' + lcr.getLeadId +
+            ' → Account ' + lcr.getAccountId +
+            ' Contact ' + lcr.getContactId +
+            ' Opportunity ' + lcr.getOpportunityId);
+    } else {
+        failCount++;
+        System.debug('FAILED: ' + lcr.getLeadId + ' | ' + lcr.getErrors[0].getMessage);
+    }
+}
+
+System.debug('Conversion complete. Success: ' + successCount + ' | Failed: ' + failCount);
+```
+
+---
+
+## Governor Limit Reference
+
+| Limit | Value | Notes |
+|---|---|---|
+| DML statements per transaction | 150 | Each `Database.update(list)` = 1 statement regardless of list size |
+| DML rows per transaction | 10,000 | Total records across all DML statements |
+| SOQL queries per transaction | 100 | Each `[SELECT ...]` in code = 1 query |
+| SOQL rows per transaction | 50,000 | Total rows returned across all queries |
+| Heap size | 6 MB (sync), 12 MB (async) | Large collections of full records can exceed this |
+| CPU time | 10,000 ms (sync), 60,000 ms (async) | Complex loops approach this limit |
+
+**For volumes > 10,000 records:** Use Apex Batch classes (`Database.Batchable`)
+which run asynchronously with 200-record batches and governor limits per batch.

package/skills/salesforce/salesforce-bulk-data-ops-skill/references/data-loader-templates.md

@@ -0,0 +1,209 @@
+# Data Loader Templates Reference
+
+## Data Loader Operation Overview
+
+| Operation | When to use | Requires Id field? |
+|---|---|---|
+| Insert | Create new records | No (Id auto-generated) |
+| Update | Modify existing records by Salesforce Id | Yes (`Id` column required) |
+| Upsert | Insert or update based on external ID | External ID field required |
+| Delete | Soft-delete records (Recycle Bin) | Yes (`Id` column required) |
+| Export | Query records to CSV | N/A |
+| Export All | Query including soft-deleted records | N/A |
+
+---
+
+## Template 1: Mass Owner Reassignment (Update)
+
+**Operation:** Update
+**Object:** Opportunity (or any object with OwnerId)
+
+**CSV header row:**
+```
+Id,OwnerId
+```
+
+**Example data:**
+```
+Id,OwnerId
+006Xx000001REPLACE1,005Xx000001NEWOWNER
+006Xx000001REPLACE2,005Xx000001NEWOWNER
+```
+
+**Notes:**
+- `OwnerId` must be the 18-character Salesforce User ID of the new owner
+- Pre-query new owner ID: `SELECT Id FROM User WHERE Username = 'newowner@company.com'`
+- Generate the Id column via export query:
+  ```
+  SELECT Id FROM Opportunity WHERE OwnerId = '<old_owner_id>'
+  ```
+- Run in sandbox first to verify ownership transfer
+
+---
+
+## Template 2: Mass Field Update (Update)
+
+**Operation:** Update
+**Object:** Account
+
+**CSV header row (example — update Rating and Industry):**
+```
+Id,Rating,Industry
+```
+
+**Example data:**
+```
+Id,Rating,Industry
+001Xx000001REPLACE1,Hot,Technology
+001Xx000001REPLACE2,Warm,Healthcare
+```
+
+**Notes:**
+- Only include the fields being changed plus `Id`
+- Do not include fields you want to preserve unchanged (they will remain unchanged)
+- Picklist values must match exact API values (case-sensitive)
+
+---
+
+## Template 3: Upsert with External ID (Upsert)
+
+**Operation:** Upsert
+**Object:** Contact
+**External ID field:** `HubSpot_Contact_ID__c`
+
+**CSV header row:**
+```
+HubSpot_Contact_ID__c,FirstName,LastName,Email,Phone
+```
+
+**Example data:**
+```
+HubSpot_Contact_ID__c,FirstName,LastName,Email,Phone
+HS-001,Jane,Smith,jane.smith@example.com,415-555-0101
+HS-002,John,Doe,john.doe@example.com,415-555-0102
+```
+
+**Notes:**
+- The external ID field must have "External ID" checked in Salesforce Setup
+- New records (no matching external ID) are inserted
+- Existing records (matching external ID) are updated
+- Do not include `Id` column — it is ignored in upsert mode
+- For relationship lookups in upsert: use `AccountId:Account:External_ID__c`
+
+---
+
+## Template 4: Bulk Soft Delete (Delete)
+
+**Operation:** Delete
+**Object:** Lead
+
+**CSV header row:**
+```
+Id
+```
+
+**Example data:**
+```
+Id
+00QXx000001REPLACE1
+00QXx000001REPLACE2
+```
+
+**Notes:**
+- Deleted records go to the Recycle Bin (15-day retention by default)
+- Hard delete (emptyRecycleBin) is T3 prohibited — do not run without explicit approval
+- Pre-export the records to a backup CSV before deleting
+- Max 10,000 records per Data Loader batch recommended
+
+---
+
+## Template 5: Lead Conversion (Insert + Update combination)
+
+Lead conversion is not directly supported by Data Loader. Use the
+Anonymous Apex template from `anonymous-apex-patterns.md`.
+
+For Data Loader lead status update (marking leads as "Converted" is
+read-only in Salesforce — proper conversion requires API call):
+
+**Alternative:** Export unconverted leads, use the Anonymous Apex
+lead conversion script, verify results.
+
+---
+
+## Data Loader Configuration Notes
+
+### Batch Size
+
+| Volume | Recommended batch size |
+|---|---|
+| < 1,000 records | 200 |
+| 1,000 – 50,000 records | 2,000 |
+| > 50,000 records | 5,000 (Bulk API v2 mode) |
+
+Configure in Data Loader: Settings → Batch Size
+
+### Bulk API v2 (Recommended for Large Volumes)
+
+Enable Bulk API v2 for operations over 10,000 records:
+- Settings → Use Bulk API: Enable
+- Settings → Bulk API v2 for query: Enable
+- Advantages: Parallel processing, higher throughput, better error reporting
+
+### Error Log
+
+Data Loader generates an error log CSV after each operation:
+- Success file: `<operation>_success_<timestamp>.csv`
+- Error file: `<operation>_error_<timestamp>.csv`
+
+Always review the error file after operations. Common errors:
+- `REQUIRED_FIELD_MISSING` — required field not in CSV
+- `INVALID_FIELD_FOR_INSERT_UPDATE` — read-only field included
+- `STRING_TOO_LONG` — value exceeds field max length
+- `INVALID_ID_FIELD` — malformed record ID
+
+---
+
+## Data Loader Export Query Templates
+
+### Export before mass update (backup)
+
+```
+SELECT Id, OwnerId, Name, StageName, CloseDate, Amount, LastModifiedDate
+FROM Opportunity
+WHERE OwnerId = '<target_user_id>'
+ORDER BY Id
+```
+
+### Export stale records before close
+
+```
+SELECT Id, Name, StageName, CloseDate, OwnerId, Amount, Account.Name
+FROM Opportunity
+WHERE IsClosed = false
+AND CloseDate < LAST_N_DAYS:90
+ORDER BY CloseDate ASC
+```
+
+### Export duplicate leads by email
+
+```
+SELECT Id, FirstName, LastName, Email, Company, Status, CreatedDate
+FROM Lead
+WHERE Email != null
+AND IsConverted = false
+ORDER BY Email, CreatedDate
+```
+
+---
+
+## Relationship Field Mapping in Data Loader
+
+To set a relationship field using an external ID (not Salesforce ID):
+
+| Lookup field | External ID syntax | Example |
+|---|---|---|
+| AccountId | `AccountId:Account:External_ID__c` | `AccountId:Account:HubSpot_Acct_ID__c` |
+| OwnerId | `OwnerId:User:Username` | `OwnerId:User:Username` (use username string) |
+| RecordTypeId | `RecordTypeId:RecordType:DeveloperName` | `RecordTypeId:RecordType:DeveloperName` |
+
+This syntax is supported in Data Loader upsert operations only.