@salesforce/afv-skills 1.8.0 → 1.9.0

package/skills/building-omnistudio-omniscript/references/best-practices.md

@@ -0,0 +1,480 @@
+<!-- Parent: building-omnistudio-omniscript/SKILL.md -->
+
+# OmniScript Best Practices
+
+> **Applies to**: OmniStudio OmniScripts (OmniProcessType='OmniScript')
+> **Companion**: See `element-types.md` for PropertySetConfig reference per element type
+
+---
+
+## Table of Contents
+
+1. [Step Design Patterns](#1-step-design-patterns)
+2. [Data Prefill Strategies](#2-data-prefill-strategies)
+3. [Validation Patterns](#3-validation-patterns)
+4. [Navigation Patterns](#4-navigation-patterns)
+5. [Performance Optimization](#5-performance-optimization)
+6. [Embedding vs Linking OmniScripts](#6-embedding-vs-linking-omniscripts)
+7. [Naming Conventions](#7-naming-conventions)
+8. [Error Handling](#8-error-handling)
+9. [Testing Strategies](#9-testing-strategies)
+10. [Security Considerations](#10-security-considerations)
+
+---
+
+## 1. Step Design Patterns
+
+### Wizard-Style (Multi-Step Sequential)
+
+The default and most common pattern. Each Step represents a phase of the process, with linear forward progression.
+
+**When to use:**
+- Guided intake forms (service requests, applications, enrollments)
+- Multi-phase data collection where later steps depend on earlier inputs
+- Processes that benefit from chunking to reduce cognitive load
+
+**Design rules:**
+- Limit each Step to 7-10 input elements (cognitive load threshold)
+- Group related fields together within a Step
+- Place data-fetching actions (DataRaptor Extract, IP Action) at the beginning of the Step they serve
+- Use descriptive Step labels that orient the user (e.g., "Contact Information", "Review & Submit")
+- The final Step should be a review/confirmation screen
+
+**Example structure:**
+```
+Step 1: "Account Selection"    -> Type Ahead (account search) + DataRaptor Extract (prefill)
+Step 2: "Service Details"      -> Select, Text, Date inputs for the request
+Step 3: "Attachments"          -> File upload + Text Area for notes
+Step 4: "Review & Submit"      -> Text Blocks displaying collected data + Submit Action
+```
+
+### Single-Page (All Elements Visible)
+
+All elements rendered on a single Step with no navigation between pages.
+
+**When to use:**
+- Simple forms with 5 or fewer inputs
+- Quick-action modals launched from FlexCards
+- Inline editing scenarios
+
+**Design rules:**
+- Use a single Step element containing all inputs
+- Omit navigation buttons (no Next/Previous needed)
+- Keep the total element count low to avoid scroll fatigue
+- Consider whether a FlexCard with inline editing would be simpler
+
+### Conditional Branching
+
+Steps are shown or hidden based on user input or data conditions.
+
+**When to use:**
+- Processes where the path varies by user selection (e.g., "New" vs "Existing" customer)
+- Compliance workflows where certain sections only apply to specific scenarios
+- Multi-product intake where product type determines required fields
+
+**Design rules:**
+- Use the `show` property on Steps with conditional expressions
+- Reference data JSON values using merge field syntax: `%ShowStep3%` or `{ShowStep3}`
+- Set controlling values early in the flow (Step 1 or data prefill)
+- Test all permutations of the conditional paths
+- Document the branching logic in Step descriptions
+
+```json
+{
+  "show": {
+    "group": {
+      "operator": "AND",
+      "rules": [
+        {
+          "field": "CustomerType",
+          "condition": "=",
+          "data": "New"
+        }
+      ]
+    }
+  }
+}
+```
+
+### Hub-and-Spoke
+
+A central Step allows navigation to sub-sections, each completing independently.
+
+**When to use:**
+- Complex case management with multiple independent sections
+- Forms where the user may complete sections in any order
+- Processes requiring non-linear data entry
+
+**Design rules:**
+- Central hub Step with Navigate Actions to each spoke
+- Each spoke completes and returns to the hub
+- Track section completion status in the data JSON
+- Display completion indicators on the hub Step
+
+---
+
+## 2. Data Prefill Strategies
+
+### DataRaptor Extract Prefill
+
+Use DataRaptor Extract Actions at the beginning of a Step to populate elements with existing Salesforce data.
+
+**Best practice:**
+- Place the Extract Action as the first element in the Step (lowest Order value)
+- Configure `executionConditionFormula` to skip the fetch if data already exists
+- Map Extract output keys to match element names for automatic binding
+- Filter the Extract query to return only the needed fields
+
+```json
+{
+  "bundle": "DR_ExtractAccountDetails",
+  "inputMap": {
+    "AccountId": "%SelectedAccountId%"
+  },
+  "outputMap": {
+    "AccountName": "AccountName",
+    "BillingAddress": "BillingAddress"
+  }
+}
+```
+
+### Integration Procedure Prefill
+
+Use IP Actions for complex prefill that requires server-side logic, aggregation, or external API calls.
+
+**Best practice:**
+- Set `remoteOptions.preTransformBundle` if data needs shaping before display
+- Use `executionConditionFormula` to avoid re-fetching on back navigation
+- Cache results in the data JSON so subsequent Steps can reference them without additional calls
+
+### Contextual Prefill (Launch Parameters)
+
+OmniScripts can receive data when launched from FlexCards, Lightning pages, or URLs.
+
+**Best practice:**
+- Document all expected launch parameters in the OmniScript description
+- Validate that required parameters are present; show an error Step if missing
+- Use Set Values elements to normalize parameter formats before processing
+
+### Save & Resume Prefill
+
+When "Save for Later" is enabled, the OmniScript restores the full data JSON on resume.
+
+**Best practice:**
+- Configure `saveNameTemplate` for meaningful save identifiers
+- Set `saveExpireInDays` to prevent stale saved instances
+- Test that all elements re-render correctly from saved JSON
+- Handle edge cases where referenced data may have changed between save and resume
+
+---
+
+## 3. Validation Patterns
+
+### Element-Level Validation
+
+Configure validation directly on input elements via PropertySetConfig.
+
+| Property | Purpose | Example |
+|----------|---------|---------|
+| `required` | Field must have a value | `"required": true` |
+| `pattern` | Regex pattern match | `"pattern": "^[A-Z]{2}\\d{6}$"` |
+| `min` / `max` | Numeric range | `"min": 1, "max": 100` |
+| `minLength` / `maxLength` | Text length range | `"minLength": 5, "maxLength": 255` |
+| `minDate` / `maxDate` | Date range | `"minDate": "TODAY", "maxDate": "+30"` |
+
+### Validation Elements
+
+Use Validation elements for cross-field and business rule validation.
+
+**Best practice:**
+- Place Validation elements at the end of a Step, before the navigation connector
+- Write clear, user-actionable error messages
+- Reference multiple fields in the validation formula for cross-field checks
+- Group related validations in a single Validation element when possible
+
+```json
+{
+  "validationFormula": "%EndDate% > %StartDate%",
+  "errorMessage": "End date must be after the start date."
+}
+```
+
+### Step-Level Validation
+
+Prevent the user from advancing to the next Step until all validations pass.
+
+**Best practice:**
+- Combine `required` properties on inputs with Validation elements for complex rules
+- Use the Step's `validationRequired` property to enforce completion
+- Display inline validation messages near the field, not only at the top of the page
+
+### Server-Side Validation
+
+Use Integration Procedure Actions for validations that require database lookups or external checks.
+
+**Best practice:**
+- Display a loading indicator during server-side validation
+- Handle timeout and error responses gracefully
+- Cache validation results to avoid redundant server calls on back-navigation
+
+---
+
+## 4. Navigation Patterns
+
+### Standard Linear Navigation
+
+Default back/forward progression through Steps.
+
+**Configuration:**
+- `allowSaveForLater`: Enable save & resume functionality
+- `cancelAction`: Define behavior when user clicks Cancel (redirect URL or close modal)
+- `showStepChart`: Display step progress indicator
+- `stepChartPlacement`: Position the step chart (top, left, right)
+
+### Conditional Step Skipping
+
+Skip Steps that are not relevant based on collected data.
+
+**Best practice:**
+- Use the `show` property on Steps rather than Navigate Actions for conditional paths
+- The OmniScript engine automatically skips hidden Steps during forward navigation
+- Test that skipped Steps do not contribute invalid data to the JSON
+
+### Custom Navigation Buttons
+
+Override default Next/Previous with Navigate Actions for non-linear flows.
+
+**Best practice:**
+- Maintain a consistent button layout across Steps
+- Label navigation buttons with the destination Step name, not generic "Next"
+- Disable the Previous button on the first Step
+- Consider whether non-linear navigation will confuse the user
+
+### Cancel and Exit
+
+**Best practice:**
+- Prompt for confirmation before discarding entered data
+- Offer "Save for Later" alongside Cancel when appropriate
+- Redirect to a meaningful page after cancellation (not a blank screen)
+
+---
+
+## 5. Performance Optimization
+
+### Lazy Loading Elements
+
+Configure action elements to execute only when their containing Step becomes visible.
+
+**Best practice:**
+- Set `executionConditionFormula` on DataRaptor Extract and IP Actions
+- Use Step-level activation triggers rather than OmniScript-level `onLoad` actions
+- Prefetch only the data needed for the first Step on initial load
+
+### Conditional Visibility vs Conditional Rendering
+
+| Approach | Behavior | Performance Impact |
+|----------|----------|--------------------|
+| `show` on elements | Element is not rendered in DOM | Lower memory, faster rendering |
+| CSS visibility | Element is rendered but hidden | Higher memory, same load time |
+
+**Best practice:**
+- Use the `show` property for elements that may not be needed at all
+- Avoid rendering large data tables or Loop Blocks that the user may never see
+
+### Data Volume in Loop Blocks
+
+Loop Blocks render elements for each item in a data array. Large arrays degrade performance.
+
+**Best practice:**
+- Limit the data array to 50 items or fewer for interactive Loop Blocks
+- Implement server-side pagination via Integration Procedures for large datasets
+- Use Type Ahead elements instead of Loop Blocks when the user needs to search/select from a large list
+
+### Minimize Action Element Count
+
+Each action element (DataRaptor, IP, Remote Action) represents a server round-trip.
+
+**Best practice:**
+- Combine multiple data fetches into a single Integration Procedure where possible
+- Fetch all data needed for a Step in one action, not one action per field
+- Use Set Values to derive calculated fields client-side instead of calling the server
+
+### Image and Static Content
+
+**Best practice:**
+- Host images on a CDN or Salesforce Static Resource rather than embedding base64 in Text Blocks
+- Minimize HTML complexity in Text Block elements
+- Use the Image element type instead of `<img>` tags in Text Blocks
+
+---
+
+## 6. Embedding vs Linking OmniScripts
+
+### Embedding (Child OmniScript)
+
+An OmniScript rendered inside another OmniScript as a reusable sub-process.
+
+**When to embed:**
+- The sub-process is a self-contained unit reused across multiple parent OmniScripts
+- The parent needs data from the child's interaction (child data merges into parent JSON)
+- The user should not leave the parent context
+
+**Design rules:**
+- Pass required data from parent to child via `prefillJSON` mapping
+- Configure the child to suppress its own navigation when embedded
+- Test data merge behavior: child data is added to the parent JSON under the child element's name
+- Avoid embedding more than 2 levels deep (parent -> child -> grandchild is the practical limit)
+- Watch for name collisions between parent and child data JSON keys
+
+### Linking (Navigate Action)
+
+A Navigate Action redirects to a separate OmniScript in a new context.
+
+**When to link:**
+- The processes are independent and do not share a data context
+- The user is transitioning from one workflow to a different one
+- The target OmniScript is also used standalone (not just as a sub-component)
+
+**Design rules:**
+- Pass context data via URL parameters or the Navigate Action's `params` property
+- The linked OmniScript starts fresh with its own data JSON
+- Handle the return navigation (redirect back to the originating page if needed)
+
+### Decision Matrix
+
+| Factor | Embed | Link |
+|--------|-------|------|
+| Data sharing needed | Yes | No |
+| Reused as standalone | Sometimes | Yes |
+| User stays in context | Yes | No |
+| Performance concern | Adds to page weight | Separate page load |
+| Depth > 2 levels | Avoid | Preferred |
+
+---
+
+## 7. Naming Conventions
+
+### OmniScript Type/SubType
+
+- **Type**: Business domain or process category. Use `PascalCase`. Examples: `ServiceRequest`, `MemberEnrollment`, `ClaimProcessing`
+- **SubType**: Specific variation or action. Use `PascalCase`. Examples: `CreateNew`, `UpdateAddress`, `FileAppeal`
+- **Language**: Use standard locale codes. Default: `English`
+
+### Element Names
+
+- Use `PascalCase` for all element names
+- Prefix action elements with their type: `DRExtract_AccountInfo`, `IP_ValidateEligibility`, `Nav_ReturnToCase`
+- Name Steps with the section they represent: `Step_ContactInfo`, `Step_ReviewSubmit`
+- Name input elements descriptively: `FirstName`, `PreferredContactMethod`, `RequestedStartDate`
+
+### Data JSON Keys
+
+- Match element names for automatic binding
+- Use consistent casing throughout the OmniScript
+- Avoid special characters, spaces, and reserved words in key names
+- Document the data JSON schema for complex OmniScripts
+
+---
+
+## 8. Error Handling
+
+### Action Element Errors
+
+Every DataRaptor, Integration Procedure, and Remote Action element should handle failures.
+
+**Best practice:**
+- Set `showError: true` and provide a meaningful `errorMessage` in PropertySetConfig
+- Use `responseJSONPath` to extract specific error details from the response
+- Implement a fallback Step that displays when critical actions fail
+- Log errors server-side via an IP Action for monitoring
+
+### User Input Errors
+
+**Best practice:**
+- Show inline error messages immediately on invalid input (not only on Step advance)
+- Use red visual indicators and position error text near the offending field
+- Provide specific guidance on how to fix the error (not just "Invalid input")
+
+### Network and Timeout Errors
+
+**Best practice:**
+- Configure `remoteTimeout` on IP Actions for long-running operations
+- Display a loading indicator during server calls
+- Offer a retry option when transient errors occur
+- If the OmniScript cannot continue, display a clear message with a support contact
+
+---
+
+## 9. Testing Strategies
+
+### Manual Testing Checklist
+
+- [ ] Walk through all Steps with valid data (happy path)
+- [ ] Attempt to advance with missing required fields
+- [ ] Enter invalid data for each validated input
+- [ ] Exercise all conditional branches (show/hide Steps and elements)
+- [ ] Test with prefilled vs empty launch parameters
+- [ ] Test Save for Later and Resume
+- [ ] Verify data is correctly submitted/saved
+- [ ] Test Cancel behavior and confirmation prompt
+- [ ] Check rendering on mobile viewport
+- [ ] Verify with different user profiles/permission sets
+
+### Integration Testing
+
+- [ ] Verify all DataRaptor Extract Actions return expected data
+- [ ] Verify all DataRaptor Load Actions create/update records correctly
+- [ ] Verify all IP Actions execute and return expected responses
+- [ ] Test with integration failures (disable a DataRaptor, verify error handling)
+- [ ] Test with large data volumes in Loop Blocks
+
+### Cross-Browser and Device Testing
+
+- [ ] Desktop: Chrome, Firefox, Safari, Edge
+- [ ] Mobile: iOS Safari, Android Chrome
+- [ ] Tablet: verify responsive layout breakpoints
+- [ ] Community/Experience Cloud: verify guest and authenticated rendering
+
+---
+
+## 10. Security Considerations
+
+### Data Exposure
+
+- OmniScript data JSON is client-side. Sensitive data (SSNs, passwords, tokens) should be processed server-side in Integration Procedures and never stored in the client JSON.
+- Use `maskValue` on sensitive input elements to prevent shoulder-surfing.
+- Strip sensitive fields from the data JSON before the Submit Action using Set Values.
+
+### Access Control
+
+- OmniScript visibility is controlled by the page or component it is placed on, not by the OmniScript itself.
+- Ensure Integration Procedures enforce record-level and field-level security (FLS).
+- Do not rely on hiding Steps or elements as a security mechanism; the data JSON can be inspected client-side.
+
+### Input Sanitization
+
+- Validate all user input before passing to DataRaptor Load or IP Actions.
+- Use `pattern` (regex) on text inputs to restrict input format.
+- Server-side IPs should validate input independently; do not trust client-side validation alone.
+
+---
+
+## 11. Common Troubleshooting
+
+| Symptom | Cause | Resolution |
+|---------|-------|------------|
+| OmniScript not rendering | OmniScript is inactive or element hierarchy is broken | Check `IsActive=true` on the OmniProcess record; verify all Steps (Level=0) and child elements are correctly parented |
+| Data not prefilling | DataRaptor Extract output mapping mismatch or wrong JSON path | Verify DataRaptor Extract output key names exactly match element names; check JSON path syntax in outputMap |
+| IP action failing silently | Integration Procedure input shape mismatch or IP is inactive | Test the IP independently with the same inputMap payload; verify IP is active; check `showError: true` is set on the action element |
+| Steps not showing | Conditional visibility expression on the Step evaluates incorrectly | Review the `show` expression on the Step element; log data JSON values to verify the controlling field is set |
+
+---
+
+## Key Takeaways
+
+1. **Keep Steps focused**: 7-10 elements maximum per Step. Split complex processes into more Steps rather than cramming elements.
+2. **Prefill early, validate often**: Load data at the start of each Step and validate before allowing progression.
+3. **Error handling is not optional**: Every server call needs a failure path. Every required input needs validation.
+4. **Performance is a design constraint**: Lazy-load data, limit Loop Block iterations, and minimize server round-trips.
+5. **Embed sparingly, link freely**: Embedding couples OmniScripts tightly. Reserve it for genuine sub-processes.
+6. **Security is server-side**: The client JSON is not a trust boundary. Sensitive logic belongs in Integration Procedures.