docs: add Salesforce Flow Engine deep-dive architecture and OpenForce implementation blueprint
This commit is contained in:
parent
929845fb9a
commit
616e7b2057
1 changed files with 111 additions and 0 deletions
111
docs/SALESFORCE_FLOW_ENGINE_SPEC.md
Normal file
111
docs/SALESFORCE_FLOW_ENGINE_SPEC.md
Normal file
|
|
@ -0,0 +1,111 @@
|
|||
# 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).
|
||||
Loading…
Reference in a new issue