@salesforce/afv-skills 1.8.0 → 1.9.0

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

@@ -0,0 +1,376 @@
+<!-- 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

@@ -0,0 +1,5 @@
+# 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

@@ -0,0 +1,88 @@
+# 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

@@ -0,0 +1,174 @@
+---
+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)."
+license: MIT
+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 |