@salesforce/afv-skills 1.8.0 → 1.9.0

package/skills/building-omnistudio-integration-procedure/references/best-practices.md

@@ -0,0 +1,388 @@
+<!-- Parent: building-omnistudio-integration-procedure/SKILL.md -->
+
+# Integration Procedure Best Practices
+
+> **Version**: 1.0.0
+> **Applies to**: OmniStudio Integration Procedures (Core namespace and Vlocity managed package)
+
+This guide consolidates best practices for building maintainable, performant, and reliable Integration Procedures.
+
+---
+
+## Table of Contents
+
+**Strategy & Planning**
+1. [When to Use an Integration Procedure](#1-when-to-use-an-integration-procedure)
+2. [IP vs Flow vs Apex: Decision Framework](#2-ip-vs-flow-vs-apex-decision-framework)
+
+**Design & Structure**
+3. [Element Ordering and Execution Flow](#3-element-ordering-and-execution-flow)
+4. [Naming Conventions](#4-naming-conventions)
+5. [Input/Output Contract Design](#5-inputoutput-contract-design)
+
+**Error Handling**
+6. [Error Handling Patterns](#6-error-handling-patterns)
+7. [Conditional Rollback](#7-conditional-rollback)
+
+**Data Operations**
+8. [Response Mapping from Data Mappers](#8-response-mapping-from-data-mappers)
+9. [Bounded Extracts and Pagination](#9-bounded-extracts-and-pagination)
+
+**Performance**
+10. [Caching Strategies](#10-caching-strategies)
+11. [Batch vs Sequential Execution](#11-batch-vs-sequential-execution)
+12. [Reducing Redundant Calls](#12-reducing-redundant-calls)
+
+**Maintenance**
+13. [Versioning with Type/SubType](#13-versioning-with-typesubtype)
+14. [Documentation Standards](#14-documentation-standards)
+
+---
+
+## 1. When to Use an Integration Procedure
+
+Integration Procedures are optimal when:
+
+- You need **declarative multi-step orchestration** combining reads, writes, transforms, and callouts
+- The process involves **multiple data sources** (Salesforce objects + external APIs)
+- You need **server-side execution** without user interaction (unlike OmniScripts)
+- The orchestration requires **conditional branching** or **loop iteration** over collections
+- You want **reusability** — the same IP can be called by OmniScripts, FlexCards, Apex, or other IPs
+
+Integration Procedures are NOT optimal when:
+
+- A single DataRaptor can accomplish the task (no orchestration needed)
+- The logic is purely computational with no data access (use Apex or a Formula)
+- You need real-time user interaction during execution (use OmniScript with embedded IP calls)
+- The process is a simple CRUD operation on one object (use a DataRaptor Load directly)
+
+---
+
+## 2. IP vs Flow vs Apex: Decision Framework
+
+| Criterion | Integration Procedure | Flow | Apex |
+|-----------|-----------------------|------|------|
+| Multi-step orchestration | Strong — designed for chaining | Possible but verbose | Manual coding required |
+| External API callouts | HTTP Action element | HTTP Callout action (GA) | Full control via HttpRequest |
+| OmniStudio integration | Native — called by OmniScript/FlexCard | Requires adapter | Requires @AuraEnabled or REST |
+| Complex business logic | Limited — use Remote Action for complex logic | Decision elements | Full language support |
+| Bulk data processing | Loop Block with batch sizing | Collection operations | SOQL/DML with governor awareness |
+| Error handling granularity | Per-element try/catch | Fault paths per DML | Full try/catch/finally |
+| Admin maintainability | Declarative, visual | Declarative, visual | Requires developer |
+| Debugging | Preview panel, debug logs | Flow debug | Apex debug logs |
+| Transaction control | Limited — each element may be its own transaction | Single transaction (before-save) or per-screen | Full transaction control |
+
+**Rule of thumb**: If the process serves OmniStudio components, use an IP. If it serves standard Salesforce UI automation, use a Flow. If it requires complex computation or fine-grained transaction control, use Apex.
+
+---
+
+## 3. Element Ordering and Execution Flow
+
+Elements execute top-to-bottom in the order they appear in the procedure definition. Follow these ordering principles:
+
+### Recommended Order
+
+1. **Set Values** — Initialize variables, set defaults, normalize input
+2. **Validation** — Conditional Block to validate required inputs before proceeding
+3. **Data Retrieval** — DataRaptor Extract or HTTP Action to fetch required data
+4. **Data Transformation** — DataRaptor Transform to shape data for downstream use
+5. **Business Logic** — Conditional Blocks, Remote Actions for decisions
+6. **Data Modification** — DataRaptor Load to write records
+7. **Response Assembly** — Set Values to build the output response
+
+### Ordering Rules
+
+- **Fetch before transform**: Extract data before attempting to reshape it
+- **Validate before mutate**: Check preconditions before performing DML
+- **Independent reads first**: Group all DataRaptor Extracts at the top where possible
+- **Error-prone steps last**: Place steps that might fail (HTTP, DML) after all preparatory work
+- **Response assembly at the end**: Build the final output after all processing completes
+
+---
+
+## 4. Naming Conventions
+
+### Type/SubType
+
+- **Type**: Business process name in PascalCase (e.g., `AccountOnboarding`, `OrderProcessing`)
+- **SubType**: Version or variant identifier (e.g., `Standard`, `v2`, `Retail`)
+- Combined format: `Type_SubType` (e.g., `AccountOnboarding_Standard`)
+
+### Element Names
+
+- Use descriptive, action-oriented names: `GetAccountDetails`, `ValidateAddress`, `CreateContactRecord`
+- Prefix with the action type for scannability: `Extract_`, `Load_`, `Transform_`, `Check_`, `Call_`
+- Avoid generic names like `Step1`, `Action2`, `Process`
+
+### Variables
+
+- Input variables: `in_variableName`
+- Output variables: `out_variableName`
+- Internal variables: `var_variableName`
+
+---
+
+## 5. Input/Output Contract Design
+
+Define clear contracts for what the IP expects and returns:
+
+### Input Contract
+
+```json
+{
+  "accountId": "001XXXXXXXXXXXX",
+  "includeContacts": true,
+  "contactLimit": 10
+}
+```
+
+- Document every expected input field with type and whether it is required
+- Set default values in a Set Values element for optional inputs
+- Validate required inputs with a Conditional Block before processing
+
+### Output Contract
+
+```json
+{
+  "success": true,
+  "account": { "Name": "Acme Corp", "Industry": "Technology" },
+  "contacts": [ { "Name": "John Doe", "Email": "john@acme.com" } ],
+  "errors": []
+}
+```
+
+- Return a consistent structure regardless of success or failure
+- Include a `success` boolean and an `errors` array in every response
+- Namespace outputs clearly so consumers know which element produced which data
+
+---
+
+## 6. Error Handling Patterns
+
+### Per-Element Error Handling
+
+Every element that performs DML or makes an external call should have error handling:
+
+1. **DataRaptor Load Actions**: Check the response for error indicators. Use a Conditional Block after the Load to inspect the result and branch to error handling if needed.
+
+2. **HTTP Actions**: Check the HTTP status code in the response. Branch on non-2xx responses.
+
+3. **Remote Actions**: Apex exceptions surface in the element response. Check for error keys in the output.
+
+### Try/Catch Pattern
+
+Structure error handling as a three-step pattern:
+
+1. **Try**: Execute the data-modifying element
+2. **Check**: Conditional Block inspects the element's response for errors
+3. **Handle**: Set Values element builds an error response or a Conditional Block routes to compensating actions
+
+### Error Response Structure
+
+```json
+{
+  "success": false,
+  "errors": [
+    {
+      "element": "CreateOrderRecord",
+      "code": "FIELD_CUSTOM_VALIDATION_EXCEPTION",
+      "message": "Order amount exceeds credit limit"
+    }
+  ]
+}
+```
+
+---
+
+## 7. Conditional Rollback
+
+When an IP performs multiple sequential DML operations and a later step fails:
+
+### Compensating Action Pattern
+
+1. After each successful DML, store the created record IDs in variables
+2. If a subsequent step fails, use stored IDs to execute compensating DataRaptor Load actions (delete/update) to undo prior changes
+3. Return a clear error response indicating which steps succeeded and which failed
+
+### Design Considerations
+
+- IPs do not have native transaction rollback across elements
+- Each DataRaptor Load action may commit independently
+- Plan for partial failure in multi-step write operations
+- Consider whether the business process can tolerate partial completion
+- For strict atomicity requirements, move the multi-DML logic to an Apex Remote Action where you control the transaction boundary
+
+---
+
+## 8. Response Mapping from Data Mappers
+
+### How Response Namespacing Works
+
+Each element's output is stored under a key matching the element name. For example, if a DataRaptor Extract element named `GetAccount` returns `{ "Name": "Acme" }`, the IP's response contains:
+
+```json
+{
+  "GetAccount": {
+    "Name": "Acme"
+  }
+}
+```
+
+### Referencing Upstream Outputs
+
+In downstream elements, reference upstream data using the element namespace:
+
+- **In PropertySetConfig**: `%GetAccount:Name%`
+- **In Set Values**: Map from `GetAccount.Name` to the target variable
+
+### Common Mapping Issues
+
+| Problem | Cause | Fix |
+|---------|-------|-----|
+| Null value in downstream element | Element name mismatch in reference | Verify exact element name spelling and case |
+| Array vs object confusion | DataRaptor returns collection, consumer expects single | Use `[0]` accessor or Transform to extract first item |
+| Nested path not resolving | Deep path syntax incorrect | Use dot notation: `GetAccount.BillingAddress.City` |
+
+---
+
+## 9. Bounded Extracts and Pagination
+
+### Setting Limits
+
+Every DataRaptor Extract Action should have a reasonable LIMIT:
+
+- Set the LIMIT in the DataRaptor definition itself, not in the IP
+- For user-facing queries, limit to 50-200 records
+- For batch processing, limit to 2000 records per iteration
+- For count/existence checks, limit to 1
+
+### Pagination Pattern
+
+For large datasets that exceed a single extract's limit:
+
+1. First extract: fetch records with LIMIT and OFFSET 0
+2. Check if result count equals LIMIT (more records may exist)
+3. Loop: increment OFFSET by LIMIT, re-extract, append results
+4. Exit when result count is less than LIMIT
+
+Avoid this pattern for datasets exceeding 10,000 records — use Apex Batch or a scheduled process instead.
+
+---
+
+## 10. Caching Strategies
+
+### When to Cache
+
+- Read-only IPs that serve reference data (picklist values, configuration)
+- IPs called frequently by multiple OmniScripts or FlexCards
+- IPs whose source data changes infrequently
+
+### When NOT to Cache
+
+- IPs that perform DML (creates, updates, deletes)
+- IPs whose output depends on the current user's permissions or context
+- IPs that return time-sensitive data (real-time pricing, inventory)
+
+### Cache Configuration
+
+Set caching properties in the IP's PropertySet:
+
+- `cacheType`: `Platform` for org-level cache, `Session` for user-session cache
+- `cacheTTL`: Time-to-live in seconds (e.g., 300 for 5 minutes, 3600 for 1 hour)
+
+### Cache Key Considerations
+
+The cache key includes the IP's Type/SubType and the input JSON. Different inputs produce different cache entries. Normalize input data to maximize cache hit rates.
+
+---
+
+## 11. Batch vs Sequential Execution
+
+### Sequential (Default)
+
+Elements execute one after another. Use when:
+
+- Each step depends on the output of the previous step
+- Strict ordering is required for business logic
+- Error handling needs to stop execution on first failure
+
+### Batch / Parallel Opportunities
+
+While IPs execute elements sequentially by default, you can optimize by:
+
+- Grouping independent DataRaptor Extracts at the beginning of the procedure
+- Using a single DataRaptor Extract with multiple output fields instead of multiple extracts
+- Combining related DataRaptor Transforms into a single transform with multiple mappings
+- Moving parallelizable logic into an Apex Remote Action that handles concurrent operations internally
+
+### Loop Block Performance
+
+- Set appropriate batch sizes for Loop Blocks processing large collections
+- Avoid nested loops — flatten data with a Transform first
+- Minimize the number of elements inside a loop body
+- Move invariant computations outside the loop
+
+---
+
+## 12. Reducing Redundant Calls
+
+### Common Redundancy Patterns
+
+| Pattern | Problem | Fix |
+|---------|---------|-----|
+| Same DataRaptor called twice | Duplicate SOQL queries | Extract once, reference the result in multiple downstream elements |
+| Nested IP re-fetches parent data | Wasted queries | Pass data as input to the nested IP instead of re-fetching |
+| Loop body fetches lookup data | N+1 query pattern | Fetch lookup data before the loop, reference it inside |
+
+### Data Passing vs Re-Fetching
+
+Prefer passing data between elements over re-fetching:
+
+- Use Set Values to copy data from one element's output to another element's input
+- Pass context data to nested IP calls as input parameters
+- Store intermediate results in variables for reuse
+
+---
+
+## 13. Versioning with Type/SubType
+
+### Versioning Strategy
+
+- Use SubType to version IPs: `Type=AccountOnboarding`, `SubType=v1` and `SubType=v2`
+- Only one version of a Type/SubType pair can be active at a time
+- Deploy and test the new version as inactive before deactivating the old version
+- Update consumers (OmniScripts, FlexCards) to reference the new SubType after activation
+
+### Migration Checklist
+
+1. Create the new IP with updated SubType
+2. Deploy and test in sandbox with the new SubType
+3. Update all consumers to reference the new SubType
+4. Activate the new IP
+5. Deactivate the old IP (do not delete until consumers are verified)
+
+---
+
+## 14. Documentation Standards
+
+### Procedure-Level Documentation
+
+Every IP should have:
+
+- A description field explaining the business purpose
+- Input/output JSON contract documented in element descriptions or external documentation
+- Dependency list (which DataRaptors, Apex classes, and nested IPs it requires)
+
+### Element-Level Documentation
+
+Every element should have:
+
+- A description explaining what it does and why
+- Notes on expected input shape and output shape
+- Error handling behavior documented
+
+### Maintenance Documentation
+
+- Record the Type/SubType and the org(s) where the IP is deployed
+- List all consumers (OmniScripts, FlexCards, Apex classes, other IPs) that call this IP
+- Note any external API dependencies with endpoint URLs and authentication method