openforce/docs/SALESFORCE_FLOW_ENGINE_SPEC.md

7.2 KiB

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).