@salesforce/afv-skills 1.22.0 → 1.24.0

package/skills/deploying-metadata/references/trigger-deployment-safety.md

@@ -1,376 +0,0 @@
-<!-- Parent: deploying-metadata/SKILL.md -->
-# Trigger Deployment Safety Guide
-
-## Overview
-
-This guide covers deployment considerations for triggers, focusing on cascade failures, atomicity patterns, and async decoupling strategies.
-
----
-
-## 1. Understanding Cascade Failures
-
-### What Are Cascade Failures?
-
-When an exception in one trigger causes rollback of operations from preceding triggers in the chain.
-
-```
-Account Insert → AccountTrigger → ContactTrigger → OpportunityTrigger
-                     ✓               ✓                 ✗ (Exception)
-
-                 All three operations ROLL BACK
-```
-
-### Default Behavior
-
-- Uncaught exceptions in triggers cause rollback of **all** operations in the transaction
-- This includes operations from other triggers that fired successfully
-- This behavior may or may not be desired depending on business requirements
-
-### When Cascade Failure is DESIRED
-
-- All operations represent ONE atomic business process
-- Example: Order with line items must be complete or not exist
-- Same business unit/persona owns all the data
-
-```apex
-// DESIRED cascade: Order and OrderItems must both succeed
-trigger OrderTrigger on Order__c (after insert) {
-    // If this fails, we WANT the Order insert to roll back
-    List<OrderItem__c> items = createDefaultLineItems(Trigger.new);
-    insert items;  // Exception here rolls back Order insert - GOOD
-}
-```
-
-### When Cascade Failure is PROBLEMATIC
-
-- Operations represent INDEPENDENT business processes
-- Example: Creating account + syncing to external CRM
-- Different business units own different parts of the process
-
-```apex
-// PROBLEMATIC cascade: CRM sync failure shouldn't prevent Account creation
-trigger AccountTrigger on Account (after insert) {
-    // If CRM sync fails, Account creation also fails - BAD
-    CRMService.syncNewAccounts(Trigger.new);  // Exception here rolls back Account
-}
-```
-
----
-
-## 2. Atomicity Patterns
-
-### Explicit Savepoints
-
-Use `Database.setSavepoint()` for explicit transaction control within a single process.
-
-```apex
-/**
- * Demonstrates explicit atomicity control for cross-object operations
- */
-public class AccountOwnership {
-
-    /**
-     * Reassigns all related records when account owner changes.
-     * This is an ATOMIC operation - all changes succeed or all roll back.
-     */
-    public static void reassignRelatedRecords(
-        List<Account> accountsWithNewOwner,
-        Map<Id, Account> oldAccountsById
-    ) {
-        // Create savepoint for atomic operation
-        Savepoint sp = Database.setSavepoint();
-
-        try {
-            Map<Id, Id> newOwnerByAccountId = buildOwnerMap(accountsWithNewOwner);
-
-            // Step 1: Reassign opportunities
-            reassignOpportunities(newOwnerByAccountId);
-
-            // Step 2: Reassign cases
-            reassignCases(newOwnerByAccountId);
-
-            // Step 3: Create transition tasks
-            createOwnerTransitionTasks(accountsWithNewOwner, oldAccountsById);
-
-        } catch (Exception e) {
-            // Rollback ALL changes if ANY step fails
-            Database.rollback(sp);
-
-            // Log the failure for investigation
-            ErrorLogger.log('AccountOwnership.reassignRelatedRecords', e);
-
-            // Re-throw to inform the caller
-            throw new AccountOwnershipException(
-                'Failed to reassign related records: ' + e.getMessage()
-            );
-        }
-    }
-}
-```
-
-### When to Use Savepoints
-
-| Scenario | Use Savepoint? | Reason |
-|----------|---------------|--------|
-| Multi-object update in same trigger | Yes | Ensures consistency |
-| Order + OrderItems creation | Yes | Business atomicity required |
-| Account + CRM sync | No | Use async decoupling instead |
-| Validation that spans objects | Yes | All-or-nothing validation |
-
----
-
-## 3. Async Decoupling Patterns
-
-### The Problem
-
-After-trigger logic that represents an independent business process can cause cascade failures.
-
-### Solution: Queueable Jobs
-
-```apex
-/**
- * Queueable job for processing that should not block the main transaction
- */
-public class AccountSyncQueueable implements Queueable, Database.AllowsCallouts {
-
-    private Set<Id> accountIds;
-    private TriggerOperation operationType;
-
-    public AccountSyncQueueable(Set<Id> accountIds, TriggerOperation operationType) {
-        this.accountIds = accountIds;
-        this.operationType = operationType;
-    }
-
-    public void execute(QueueableContext context) {
-        try {
-            List<Account> accounts = [
-                SELECT Id, Name, Website, Industry, BillingAddress
-                FROM Account
-                WHERE Id IN :accountIds
-            ];
-
-            switch on operationType {
-                when AFTER_INSERT {
-                    ExternalCRM.createAccounts(accounts);
-                }
-                when AFTER_UPDATE {
-                    ExternalCRM.updateAccounts(accounts);
-                }
-                when AFTER_DELETE {
-                    ExternalCRM.deleteAccounts(accountIds);
-                }
-            }
-
-        } catch (Exception e) {
-            // Log error but don't fail - this is independent of main transaction
-            ErrorLogger.log('AccountSyncQueueable', e, accountIds);
-        }
-    }
-}
-```
-
-### Usage in Trigger Handler
-
-```apex
-public void afterInsert(List<Account> newAccounts, Map<Id, Account> newAccountsById) {
-    // Synchronous operations that SHOULD block
-    AccountNotifications.notifySalesTeam(newAccounts);
-
-    // Async operations that should NOT block main transaction
-    if (canEnqueueJob()) {
-        System.enqueueJob(new AccountSyncQueueable(
-            newAccountsById.keySet(),
-            TriggerOperation.AFTER_INSERT
-        ));
-    }
-}
-
-private Boolean canEnqueueJob() {
-    return !System.isBatch() &&
-           !System.isFuture() &&
-           Limits.getQueueableJobs() < Limits.getLimitQueueableJobs();
-}
-```
-
-### Platform Events for Maximum Decoupling
-
-```apex
-// Publisher (in trigger)
-EventBus.publish(new Account_Changed__e(
-    Account_Id__c = account.Id,
-    Change_Type__c = 'INSERT'
-));
-
-// Subscriber (separate trigger on platform event)
-trigger AccountChangedSubscriber on Account_Changed__e (after insert) {
-    // Process events - failures here don't affect original transaction
-    List<Id> accountIds = new List<Id>();
-    for (Account_Changed__e event : Trigger.new) {
-        accountIds.add(event.Account_Id__c);
-    }
-    // Sync to external system
-}
-```
-
-### Decoupling Decision Matrix
-
-| Business Process | Same User Persona? | Failure Impact | Recommendation |
-|-----------------|-------------------|----------------|----------------|
-| Order + Line Items | Yes | Must be atomic | Synchronous + Savepoint |
-| Account + Audit Log | Yes | Can retry | Queueable |
-| Account + External CRM | No | Independent | Platform Event |
-| Contact + Marketing Cloud | No | Independent | Platform Event |
-| Record + Email Notification | Yes | Non-critical | @future |
-
----
-
-## 4. Pre-Deployment Checklist
-
-### Trigger Cascade Analysis
-
-Before deploying triggers, analyze the cascade impact:
-
-```
-CHECKLIST:
-□ List all triggers that fire on the same transaction
-□ Identify which operations are atomic (same business process)
-□ Identify which operations are independent (different processes)
-□ Verify exception handling in each trigger
-□ Check for recursive trigger prevention
-□ Review async job usage and limits
-```
-
-### Questions to Answer
-
-1. **What triggers will fire together?**
-   - Map the full trigger chain for each DML operation
-   - Include triggers on related objects (parent-child)
-
-2. **What happens if each trigger fails?**
-   - Which operations will roll back?
-   - Is that the desired behavior?
-
-3. **Are there external system calls?**
-   - Should they be async?
-   - What happens if they fail?
-
-4. **What about governor limits?**
-   - How many DML statements in the chain?
-   - How many SOQL queries?
-   - Can bulk operations stay within limits?
-
----
-
-## 5. Testing Cascade Scenarios
-
-### Test Cascade Success
-
-```apex
-@IsTest
-static void testTriggerChain_AllSucceed() {
-    Test.startTest();
-    Account acc = new Account(Name = 'Test');
-    insert acc;  // Should fire AccountTrigger, create child records, etc.
-    Test.stopTest();
-
-    // Verify all expected records were created
-    Assert.areEqual(1, [SELECT COUNT() FROM Contact WHERE AccountId = :acc.Id]);
-    Assert.areEqual(1, [SELECT COUNT() FROM Task WHERE WhatId = :acc.Id]);
-}
-```
-
-### Test Cascade Failure (Expected Rollback)
-
-```apex
-@IsTest
-static void testTriggerChain_ChildFailure_RollsBack() {
-    // Configure scenario that will cause child trigger to fail
-    Test.startTest();
-    try {
-        Account acc = new Account(Name = 'Trigger Failure Test');
-        insert acc;
-        Assert.fail('Expected DmlException');
-    } catch (DmlException e) {
-        // Expected - verify Account was NOT created
-        Assert.areEqual(0, [SELECT COUNT() FROM Account WHERE Name = 'Trigger Failure Test']);
-    }
-    Test.stopTest();
-}
-```
-
-### Test Async Decoupling
-
-```apex
-@IsTest
-static void testAccountInsert_CRMSyncAsync_DoesNotBlock() {
-    // Even if CRM sync would fail, Account should be created
-    Test.startTest();
-    Account acc = new Account(Name = 'Async Test');
-    insert acc;
-    Test.stopTest();
-
-    // Account should exist regardless of async job outcome
-    Assert.areEqual(1, [SELECT COUNT() FROM Account WHERE Name = 'Async Test']);
-
-    // Verify async job was enqueued
-    Assert.areEqual(1, [SELECT COUNT() FROM AsyncApexJob WHERE JobType = 'Queueable']);
-}
-```
-
----
-
-## 6. Deployment Commands for Trigger Safety
-
-### Validate Before Deploying
-
-```bash
-# Always validate triggers before deploying
-sf project deploy start --dry-run \
-    --source-dir force-app/main/default/triggers \
-    --source-dir force-app/main/default/classes \
-    --test-level RunLocalTests \
-    --target-org alias
-```
-
-### Deploy with Test Coverage
-
-```bash
-# Deploy triggers with their test classes
-sf project deploy start \
-    --source-dir force-app/main/default/triggers \
-    --source-dir force-app/main/default/classes \
-    --test-level RunSpecifiedTests \
-    --tests AccountTriggerTest,ContactTriggerTest \
-    --target-org alias
-```
-
-### Verify Trigger Order
-
-After deployment, verify trigger execution order if you have multiple triggers on the same object:
-
-```bash
-# Query trigger execution order (via Debug Logs)
-sf apex tail log --target-org alias
-
-# Or check in Setup: Object Manager → [Object] → Triggers
-```
-
----
-
-## Summary
-
-| Pattern | Use Case | Trade-off |
-|---------|----------|-----------|
-| **Default (Cascade)** | Atomic business processes | Simple but all-or-nothing |
-| **Savepoint** | Controlled rollback within handler | More code, explicit control |
-| **Queueable** | Independent async processes | Decoupled but async limits |
-| **Platform Event** | Maximum decoupling | More infrastructure |
-| **@future** | Simple fire-and-forget | Limited parameters |
-
-### Key Principles
-
-1. **Make atomicity decisions explicit** - Don't rely on default behavior accidentally
-2. **Decouple independent processes** - Use async for cross-domain operations
-3. **Test cascade scenarios** - Verify both success and failure paths
-4. **Document trigger chains** - Future maintainers need to understand dependencies
-5. **Validate before deploying** - Use `--dry-run` to catch issues early

package/skills/deploying-omnistudio-datapacks/CREDITS.md

@@ -1,5 +0,0 @@
-# Credits & Acknowledgments
-
-This skill is based on practical OmniStudio/Vlocity DataPack deployment workflows and the Vlocity Build command model.
-
----

package/skills/deploying-omnistudio-datapacks/README.md

@@ -1,88 +0,0 @@
-# deploying-omnistudio-datapacks
-
-Salesforce Industries DataPack deployment automation using Vlocity Build. Export, validate, deploy, retry, and compare OmniStudio/Vlocity DataPacks with predictable workflow guardrails.
-
-## Features
-
-- **DataPack Deployment Workflow**: Run `packExport`, `packDeploy`, `packRetry`, `packContinue`, and `packGetDiffs`
-- **Job File Guidance**: Build deterministic `projectPath`, `expansionPath`, `queries`, and `manifest` job patterns
-- **Validation-First Operations**: Gate deployment with `validateLocalData` and dependency checks
-- **Failure Triage**: Diagnose matching-key, GlobalKey, dependency, and configuration drift failures
-- **CI/CD Patterns**: Support manifest-driven and git-aware deployment sequencing
-
-## Usage
-
-Invoke this skill when working with OmniStudio/Vlocity DataPack deployments:
-
-```
-Skill: deploying-omnistudio-datapacks
-Request: "Deploy my OmniStudio DataPacks to UAT using Vlocity Build and include retry guidance."
-```
-
-## Common Operations
-
-| Operation | Example Request |
-|-----------|-----------------|
-| Export | "Export DataPacks from source org with this job file." |
-| Validate local files | "Run pre-deploy validation and identify key issues." |
-| Deploy | "Deploy DataPacks to target org using packDeploy." |
-| Retry failures | "Run packRetry and summarize what remains." |
-| Resume interrupted run | "Continue the failed deployment job." |
-| Compare with target | "Run packGetDiffs and report drift." |
-
-## Key Commands
-
-```bash
-# Validate local DataPack integrity
-vlocity -sfdx.username [sourceAlias] -job [jobFile].yaml validateLocalData
-
-# Export from source
-vlocity -sfdx.username [sourceAlias] -job [jobFile].yaml packExport
-
-# Deploy to target
-vlocity -sfdx.username [targetAlias] -job [jobFile].yaml packDeploy
-
-# Retry failed DataPacks
-vlocity -sfdx.username [targetAlias] -job [jobFile].yaml packRetry
-
-# Continue interrupted execution
-vlocity -sfdx.username [targetAlias] -job [jobFile].yaml packContinue
-
-# Compare local files to target org
-vlocity -sfdx.username [targetAlias] -job [jobFile].yaml packGetDiffs
-```
-
-## Best Practices
-
-| Rule | Details |
-|------|---------|
-| Validate first | Run `validateLocalData` before deploy |
-| Keep scope minimal | Prefer manifest/key-scoped deploys for safer rollouts |
-| Retry intentionally | Use `packRetry` while error count is decreasing |
-| Preserve key strategy | Keep matching keys and GlobalKeys consistent across orgs |
-| Compare post-deploy | Run `packGetDiffs` to verify target parity |
-
-## Cross-Skill Integration
-
-| Related Skill | When to Use |
-|---------------|-------------|
-| deploying-metadata | Deploy non-DataPack Salesforce metadata with `sf project deploy` |
-| building-omnistudio-omniscript | Author OmniScripts before deployment |
-| building-omnistudio-flexcard | Build FlexCards before deployment |
-| building-omnistudio-integration-procedure | Build Integration Procedures before deployment |
-| debugging-apex-logs | Investigate runtime/triggers/log failures surfaced during deploy |
-
-## Documentation
-
-- [SKILL.md](SKILL.md) - Full DataPack deployment workflow and operating rules
-- [references/job-file-template.md](references/job-file-template.md) - Baseline job file patterns
-- [references/troubleshooting-matrix.md](references/troubleshooting-matrix.md) - Common failures and fix directions
-- [examples/business-internet-plus-bundle/TRANSCRIPT.md](examples/business-internet-plus-bundle/TRANSCRIPT.md) - Validation planning/execution transcript and outcomes
-- [examples/business-internet-plus-bundle-deploy/TRANSCRIPT.md](examples/business-internet-plus-bundle-deploy/TRANSCRIPT.md) - Deployment execution transcript with packDeploy/packRetry results
-
-## Requirements
-
-- Node.js 18+
-- Vlocity Build CLI (`npm install --global vlocity`)
-- Salesforce CLI v2 (for org auth and context)
-- Source and target org access

package/skills/deploying-omnistudio-datapacks/SKILL.md

@@ -1,173 +0,0 @@
----
-name: deploying-omnistudio-datapacks
-description: "Salesforce Industries DataPack deployment automation using Vlocity Build. TRIGGER when: user deploys or validates OmniStudio/Vlocity DataPacks with vlocity commands (packDeploy/packRetry/packExport/packGetDiffs), sets up DataPack CI/CD pipelines, or troubleshoots DataPack migration errors. DO NOT TRIGGER when: deploying Salesforce metadata with sf project deploy (use deploying-metadata), authoring OmniStudio artifacts (use building-omnistudio-*), or writing Apex/LWC business logic (use generating-apex/generating-lwc-components)."
-metadata:
-  version: "1.0"
----
-
-# deploying-omnistudio-datapacks: Vlocity Build DataPack Deployment
-
-Use this skill when the user needs **Vlocity DataPack deployment orchestration**: export/deploy workflow, manifest-driven deploys, failure triage, and CI/CD sequencing for OmniStudio/Industries DataPacks.
-
----
-
-## Scope
-
-Use `deploying-omnistudio-datapacks` when work involves:
-- `vlocity packDeploy`, `packRetry`, `packContinue`, `packExport`, `packGetDiffs`, `validateLocalData`
-- DataPack job-file design (`projectPath`, `expansionPath`, `manifest`, `queries`)
-- org-to-org DataPack migration and retry loops
-- troubleshooting DataPack dependency, matching-key, and GlobalKey issues
-
-Delegate elsewhere when the user is:
-- deploying standard metadata with `sf project deploy` -> [deploying-metadata](../deploying-metadata/SKILL.md)
-- building OmniScripts, FlexCards, IPs, or Data Mappers -> `building-omnistudio-*`
-- designing Product2 EPC bundles -> [modeling-omnistudio-epc-catalog](../modeling-omnistudio-epc-catalog/SKILL.md)
-- writing Apex/LWC code -> [generating-apex](../generating-apex/SKILL.md), [generating-lwc-components](../generating-lwc-components/SKILL.md)
-
----
-
-## Critical Operating Rules
-
-- Use **Vlocity Build (`vlocity`)** commands for DataPacks, not `sf project deploy`.
-- Prefer Salesforce CLI auth integration (`-sfdx.username <alias>`) over username/password files when available.
-- Always run a **pre-deploy quality gate** before full deploy:
-  1) `validateLocalData`
-  2) optional `packGetDiffs`
-  3) then `packDeploy`
-- Use `packRetry` repeatedly when error counts are dropping; stop when retries no longer improve results.
-- Keep matching-key strategy and GlobalKey integrity consistent across source and target orgs.
-
----
-
-## Required Context to Gather First
-
-Ask for or infer:
-- source org and target org aliases
-- job file path and DataPack project path
-- deployment scope (full project, manifest subset, or specific `-key`)
-- whether this is export, deploy, retry, continue, or diff-only
-- namespace model (`%vlocity_namespace%`, `vlocity_cmt`, or core)
-- known constraints (new sandbox bootstrap, trigger behavior, matching key customizations)
-
-Preflight checks:
-
-```bash
-vlocity help
-sf org list
-sf org display --target-org <alias> --json
-test -f <job-file>.yaml
-```
-
----
-
-## Recommended Workflow
-
-### 1. Ensure tool readiness
-```bash
-npm install --global vlocity
-vlocity help
-```
-
-### 2. Validate project data locally
-```bash
-vlocity -sfdx.username <source-alias> -job <job-file>.yaml validateLocalData
-```
-
-Use `--fixLocalGlobalKeys` only when explicitly requested and after explaining impact.
-
-### 3. Export from source (when needed)
-```bash
-vlocity -sfdx.username <source-alias> -job <job-file>.yaml packExport
-vlocity -sfdx.username <source-alias> -job <job-file>.yaml packRetry
-```
-
-### 4. Deploy to target
-```bash
-vlocity -sfdx.username <target-alias> -job <job-file>.yaml packDeploy
-vlocity -sfdx.username <target-alias> -job <job-file>.yaml packRetry
-```
-
-### 5. Continue interrupted jobs
-```bash
-vlocity -sfdx.username <target-alias> -job <job-file>.yaml packContinue
-```
-
-### 6. Verify post-deploy parity
-```bash
-vlocity -sfdx.username <target-alias> -job <job-file>.yaml packGetDiffs
-```
-
-Job-file starter: [references/job-file-template.md](references/job-file-template.md)
-
----
-
-## Gotchas
-
-| Error / symptom | Likely cause | Default fix direction |
-|---|---|---|
-| `No match found for ...` | missing dependency in target org | include missing DataPack key and redeploy |
-| `Duplicate Results found for ... GlobalKey` | duplicate records in target | clean duplicates and re-run deploy |
-| `Multiple Imported Records ... same Salesforce Record` | source duplicate matching-key records | remove duplicates in source and re-export |
-| `No Configuration Found` | outdated DataPack settings | run `packUpdateSettings` or enable `autoUpdateSettings` |
-| `Some records were not processed` | settings mismatch / partial dependency state | refresh settings both orgs, then retry |
-| SASS / template compile failures | missing referenced UI template assets | export/deploy referenced template dependencies first |
-
-Detailed matrix: [references/troubleshooting-matrix.md](references/troubleshooting-matrix.md)
-
----
-
-## CI/CD Guidance
-
-Default pipeline shape:
-1. authenticate orgs (`sf org login ...`)
-2. validate local DataPack integrity (`validateLocalData`)
-3. export changed scope (`packExport` or manifest-driven export)
-4. deploy (`packDeploy`)
-5. retry loop (`packRetry`) until stable
-6. compare (`packGetDiffs`) and publish deployment report
-
-For incremental deploy optimization, use job-file options such as:
-- `gitCheck: true`
-- `gitCheckKey: <folder>`
-- `manifest` for deterministic scope control
-
----
-
-## Cross-Skill Integration
-
-| Need | Delegate to | Reason |
-|---|---|---|
-| metadata deploy outside DataPacks | [deploying-metadata](../deploying-metadata/SKILL.md) | Metadata API workflows |
-| OmniStudio component authoring | `building-omnistudio-*` | build artifacts before deploy |
-| EPC product and offer payload authoring | [modeling-omnistudio-epc-catalog](../modeling-omnistudio-epc-catalog/SKILL.md) | Product2/DataPack model quality |
-| Apex trigger/log error diagnosis | [debugging-apex-logs](../debugging-apex-logs/SKILL.md), [generating-apex](../generating-apex/SKILL.md) | automation-side root-cause fixes |
-
----
-
-## Output Expectations
-
-After completing a DataPack operation, deliver a completion block:
-
-```text
-DataPack goal: <export / deploy / retry / diff / ci-cd>
-Source org: <alias or N/A>
-Target org: <alias or N/A>
-Scope: <job file + manifest/key/full>
-Result: <passed / failed / partial>
-Key findings: <errors, dependencies, retries, diffs>
-Next step: <safe follow-up action>
-```
-
----
-
-## Reference File Index
-
-| File | When to read |
-|------|-------------|
-| `references/job-file-template.md` | Before advising on job file structure — load as baseline configuration reference |
-| `references/troubleshooting-matrix.md` | When user reports deploy failures — load to diagnose DataPack errors and apply fix directions |
-| `examples/business-internet-plus-bundle/TRANSCRIPT.md` | Example of validation planning and execution for a Product2 bundle |
-| `examples/business-internet-plus-bundle/deploy-business-internet-plus-bundle.yaml` | Example job file for scope-limited `validateLocalData` run |
-| `examples/business-internet-plus-bundle-deploy/TRANSCRIPT.md` | Example of full deploy cycle including `packDeploy` and `packRetry` outcomes |
-| `examples/business-internet-plus-bundle-deploy/deploy-business-internet-plus-bundle.yaml` | Example job file for staged deployment with manifest targeting |