# Salesforce Flow Engine Deep Dive & OpenForce Implementation Blueprint ## 1. Executive Summary & Objective Salesforce Flow (Lightning Flow / Flow Builder) is Salesforce's visual Turing-complete orchestration and declarative automation engine. It subsumed Workflow Rules, Process Builder, and Visual Workflow into a unified DAG-driven runtime. To achieve Salesforce parity in **OpenForce**, we must bridge the gap between our current DAG topology checker (`Kahn's algorithm`) and Salesforce's full Flow runtime specification: 1. **Flow Types & Trigger Subsystems** (Record-Triggered, Schedule-Triggered, Autolaunched, Subflows). 2. **Core Flow Elements** (Interaction, Logic/Conditionals, Data DML operations). 3. **Execution Semantics & State Machine** (Variables, Evaluation Loops, Bulkification, Transaction Boundaries). 4. **Custom `__c` Field Support on Standard CRM Objects** (Extensible JSONB metadata overlay on `Account`, `Contact`, `Lead`, `Opportunity`). --- ## 2. Salesforce Flow Engine Architecture Deconstruction ### 2.1 The 4 Primary Flow Types & Triggers | Flow Type | Trigger Mechanism | Equivalent Salesforce Concept | OpenForce Target Implementation | | :--- | :--- | :--- | :--- | | **Record-Triggered Flow** | `post_save` / `pre_save` model lifecycle | Before-Save (Fast Field Updates) & After-Save (Related Records & Actions) | Django model signals (`post_save`, `pre_delete`) routing to `FlowDispatcher` | | **Schedule-Triggered Flow** | Batch cron / recurrent time interval | Runs on a specified frequency (Once, Daily, Weekly) for a batch of records | Celery Beat / Redis queue dispatching chunks of record IDs | | **Autolaunched Flow (No Trigger)** | Invoked imperatively via API, Apex, or REST | Can be called by external systems, buttons, or parent flows | `POST /api/workflows/{id}/execute/` | | **Subflow** | Invoked as an element within another flow | Reusable modular automation with defined Input/Output parameters | `SubflowElement` executing a child `FlowDefinition` within parent context | ### 2.2 Complete Flow Element Taxonomy Salesforce divides Flow elements into three core categories: #### A. Logic Elements 1. **Decision (`DecisionNode`)**: - Multiple outcome branches (e.g. `High Value`, `Mid Tier`, `Default/Else`). - Each outcome contains a set of logic conditions (e.g., `{!Record.amount} >= 50000 AND {!Record.stage} == 'Proposal'`). - Condition operators: `equals`, `not_equals`, `greater_than`, `less_than`, `contains`, `is_null`. - Supports custom condition logic: `AND`, `OR`, custom expressions (`(1 AND 2) OR 3`). 2. **Assignment (`AssignmentNode`)**: - Sets, increments, decrements, or appends values to variables. - Operators: `Equals`, `Add`, `Subtract`, `Add to Collection`, `Remove from Collection`. 3. **Loop (`LoopNode`)**: - Iterates over a collection of records or variables (e.g., all `OpportunityLineItems` on an `Opportunity`). - Emits `For Each` child execution branch and `After Last` exit branch. 4. **Subflow (`SubflowNode`)**: - Calls an active Flow definition. - Maps parent context variables $ ightarrow$ child input variables, and child output variables $ ightarrow$ parent context. #### B. Data (DML) Elements 1. **Create Records (`CreateRecordNode`)**: - Inserts 1 or multiple records into standard or custom objects (`Lead`, `Account`, `CustomRecord__c`). 2. **Update Records (`UpdateRecordNode`)**: - Updates records matching filter conditions or updates the triggering `{!$Record}`. 3. **Get Records (`GetRecordsNode`)**: - Queries database with filter conditions, sort order, and limit (`Find First` vs `Find All`). 4. **Delete Records (`DeleteRecordNode`)**: - Removes records matching criteria. #### C. Action Elements 1. **Send Email / Outreach**: - Dispatches transactional email or triggers outreach campaign with merge tags. 2. **Post to Chatter / Feed**: - Creates a polymorphic `Activity` / note on the target record. 3. **Custom Action / Webhook / Task**: - Spawns background tasks or invokes external webhooks. --- ## 3. Dynamic Custom Fields (`__c`) on Standard Objects ### 3.1 Architectural Analysis & Pattern Selection In Salesforce, `Account`, `Contact`, `Lead`, and `Opportunity` seamlessly accept `custom_field__c` without database downtime or schema migrations. **Recommended Pattern for OpenForce:** - Keep existing relational columns for core standard fields (for high-speed relational queries, foreign keys, and indexes). - Add a `custom_fields = models.JSONField(default=dict, blank=True)` column with PostgreSQL GIN index (`gin (custom_fields jsonb_path_ops)`) to `Account`, `Contact`, `Lead`, and `Opportunity`. - Update `CustomFieldDefinition` to support standard object attachment via an `entity_name` attribute (e.g. `entity_name="Account"`, `entity_name="Lead"`, or `custom_object=custom_obj_id`). - When serializing or validating standard models, validate `custom_fields` against registered `CustomFieldDefinition` records for that entity using `schema_engine.validate_record_data`. --- ## 4. Phase 4 Technical Specification: The 3 Core Enhancements ### Task 1: Standard Objects Dynamic Custom Fields Engine 1. **Model Modification**: - Add `custom_fields = models.JSONField(default=dict, blank=True)` to `Account`, `Contact`, `Lead`, `Opportunity`. - Add GIN index on `custom_fields` across all 4 standard models. 2. **Field Registry**: - Enable `CustomFieldDefinition` to belong either to a `CustomObjectDefinition` or a `standard_entity` (`'Account'`, `'Contact'`, `'Lead'`, `'Opportunity'`). - Automatically enforce `__c` naming convention on standard entity custom fields. 3. **Serializer & Dynamic Deserialization**: - Update `crm_core/serializers.py` to dynamically surface `custom_fields` as top-level fields or under `custom_fields`, validating with `Draft7Validator`. ### Task 2: Advanced Flow Builder Execution Engine 1. **Decision Branching Runtime**: - Add `decision` node execution in `workflows/engine.py`. - Evaluate outcomes sequentially; take the first matching branch or `default_outcome`. 2. **Subflow Execution**: - In `workflows/engine.py`, when a `subflow` node is encountered, load the child `FlowDefinition`, map inputs, run child DAG, and pull outputs back into parent context. 3. **Loop & Dynamic Context Resolution**: - Support nested expression evaluation (`{!Record.amount}`, `{!Context.score}`). ### Task 3: Trigger Subsystems & Scheduling 1. **Record-Change Triggers**: - Implement Django `post_save` and `post_delete` signal handlers in `workflows/signals.py`. - Filter active `FlowDefinition` records where `trigger_type='record_created'` or `'record_updated'`. - Dispatch matching flows synchronously or asynchronously via Celery worker. 2. **Scheduled Flow Triggers**: - Add `cron_expression` or interval settings to `FlowDefinition`. - Expose management command / Celery Beat task `dispatch_scheduled_flows` that queries eligible records and launches flow batches. --- ## 5. Architectural Verification & Quality Contract - Zero breaking changes to existing 55 passing tests. - Maintain $\ge 85\%$ test coverage across new workflow elements and custom field models. - Transactional atomicity: if an after-save record-triggered flow raises an unhandled error, the triggering DML transaction rolls back cleanly (Salesforce all-or-nothing semantic).