Running Calculations

Running Calculations

Plan calculations run server-side through the orchestration engine. You start a run explicitly with Run Calculation on the Plan Preferences page, or automatically when Auto Update is enabled and inputs change.

Starting a run

Orchestration status values

Status	Meaning
Not Started	No orchestration job has run for this plan yet
Submitted	Job enqueued; waiting to start processing
Processing	Calculation stages executing in Apex queueable jobs
DTO_Ready	Phase-1 projections available for UI review; persistence may still be running
Completed	Calculation finished; transitioning to durable ready state
Ready	Terminal success—projections saved and charts current
Failed	Terminal error—check Run History and troubleshooting guidance
Out of Date	Inputs changed since last successful run—recalculate to refresh
Status_Unavailable	Synthetic read failure when status cannot be loaded—not the same as Not Started. Check plan record access. See Troubleshooting.

DTO_Ready vs Ready: Charts may refresh when projections are ready for review (DTO_Ready) before the plan reaches final Ready status. This is expected—the UI distinguishes “ready for review” from “fully saved.”

Auto Update

Auto Update in System Settings controls whether input changes enqueue a new run without clicking Run Calculation. Options are typically On and Off.

• On — Convenient for active planning; watch for overlapping runs on large plans
• Off — You batch edits, then run once manually

The engine blocks duplicate enqueue while a run is in flight (Submitted, Processing, or DTO_Ready). Wait for a terminal state before forcing another run if the button appears disabled.

Run History

Open Run History in the left navigation to review Orchestration run history for the plan. Enable Record Orchestration History on the plan (where exposed) for durable run rows.

Column / field	Meaning
Status	Run outcome (Ready, Failed, and intermediate states)
Source	Async, Sync, or Scenario origin
Run Id	Correlation id matching Last_Run_Id__c on the plan
Started / Completed	Run timestamps
Failure Stage	Pipeline stage where a failed run stopped
Engine Version	Packaged calculation engine version
Job Id	Salesforce async job identifier
Error Message	User-safe failure summary

Filter runs by All, Async, Sync, or Scenario. Administrators with FinPlan_Admin may see diagnostic payload previews on failed runs.

Plan run fields (Plan Preferences)

Field	Purpose
Last_Run_Id__c	Current run correlation
Last_Run_Started_At__c / Last_Run_Completed_At__c	Run timing
Last_Run_Dto_Ready_At__c	Phase-1 projection availability marker
Last_Run_Failure_Stage__c	Failure location for the latest run
Last_Run_Engine_Version__c	Engine version used
Orchestration_Error_Message__c	Latest error summary on the plan record

What orchestration produces

• Multi-year financial projections persisted to projection storage (JSON chunks on FinPlan_Financial_Projections_XML__c in current package versions, plus legacy row objects where present)
• Tax bracket payment records on FinPlan_Tax_Bracket_Payment__c
• Updated orchestration fields on the Financial Plan record
• Optional run history rows on FinPlan_Orchestration_Run__c

Charts under Insights read this persisted data—they do not recalculate on the client.

Advanced: orchestration architecture

Orchestration uses FinPlan_Plan_Orchestration to enqueue FinPlan_Orchestration_Queueable jobs. Status contract helpers live in FinPlan_OrchestrationStatusContract (Apex) with a JavaScript mirror in finPlanOrchestrationStatusContract. A single finPlanOrchestrationStatusCoordinator polls status per plan.

Full detail: Orchestration Internals.

Related: Reading Insights, Troubleshooting.