oxFlow Wiki

Commercials & Submission

7 min read

Turning total cost into revenue. Applies sequenced Rules, derives Submission Values, supports per-Item overrides, and drives Publisher output.

Primary views: Commercials (view 13) · Publisher (view 14) Related entities: Commercials · Item · Estimate

1. The three Commercials entities

EntityRole
RuleA single commercial adjustment (Contingency, Margin, Risk allowance, etc.). Multiple per Estimate, applied in sequence.
Submission ValueThe final rate / amount shown to the client for a Schedule Item. Computed by Rules; manually overridable. 1:1 with Schedule Items.
Publisher OutputThe submittable artifact (PDF / Excel) sent to the client. Latest per Estimate only.

2. Flow

 Estimate (In Progress or Reviewed, costed)
 │
 ▼
 ┌─────────────────────────────────┐
 │ Commercials view │
 └─────────────────────────────────┘
 │
 ┌──────────────┼───────────────┐
 ▼ ▼ ▼
 ┌────────────┐ ┌─────────────┐ ┌──────────────┐
 │ Add Rules │ │ Review │ │ Override a │
 │ in │ │ Submission │ │ Submission │
 │ sequence │ │ Values │ │ Value │
 │ (Percent / │ │ (computed) │ │ (estimator │
 │ Lump Sum) │ │ │ │ decision) │
 └────────────┘ └─────────────┘ └──────────────┘
 │ │ │
 └──────────────┼───────────────┘
 │
 ▼
 Final Submission Values ready
 │
 ▼
 ┌────────────────────────┐
 │ Publisher view │
 └────────────────────────┘
 │
 Edit cover letter,
 conditions, inclusions,
 exclusions, branding
 │
 ▼
 Publish
 │
 Submit gate check
 │ │
 fail (Unpriced/Plugged) pass (all Priced/
 → blocking list; no Reviewed/Locked)
 transition │
 ▼
 Publisher Output → Published
 Estimate → Submitted
 Items → Locked
 Tender → Submitted (if first publish)

3. Rules — types, scope, sequence

3.1 Rule types

Two types in v1. Rate Adjustment is deliberately not a Rule type — it’s handled via Submission Value overrides.

TypeBehaviourTypical use
PercentageApplied to running total as a percentage (compounding on prior rules)Contingency 5%, Margin 8%, Risk 3%
Lump SumFixed dollar amount, distributed proportionally across in-scope Items by cost shareRisk allowance $20K, preliminaries allowance $50K

3.2 Rule scope targets

A Rule targets Items via one or more scope targets. Multiple scope targets combine with AND semantics — an Item must match all scope targets for the Rule to apply.

v1 scope target types:

  1. All — every Item in the Estimate
  2. Direct-only — Items structurally direct (Schedule + their descendants), unless overridden by Indirect Cost flag
  3. Indirect-only — Items structurally indirect or flagged as Indirect Cost
  4. Specific Heading (subtree) — everything under a chosen Heading
  5. Item Type — e.g., all Schedule Items, all Provisional Sums
  6. Resource Type — e.g., all Labour Resources (applies to the cost contribution of those Resources across the Estimate)
  7. Categorization Option — e.g., all Items tagged “Mechanical”
  8. Code value — e.g., all Items with Workcentre = “Civil”
  9. Specific Item — surgical adjustment to one Item

3.3 Sequence and running state

Rules apply in ascending sequence_order. Each Rule operates on the running state of its scope — i.e., after all prior Rules in the sequence have been applied.

Critical property: changing rule order changes the final totals. This is intentional. For example:

Cost: $100,000
Rule 1: Contingency 5% → +$5,000 → running $105,000
Rule 2: Margin 8% → +$8,400 → running $113,400 (8% of $105K, not $100K)

vs.

Cost: $100,000
Rule 1: Margin 8% → +$8,000 → running $108,000
Rule 2: Contingency 5% → +$5,400 → running $113,400

Both happen to land at the same final total here (commutative for stacked percentages), but mixed Percentage / Lump Sum sequences are order-sensitive.

3.4 Lump Sum distribution

When a Lump Sum Rule’s scope covers multiple Items, the amount is distributed proportionally across in-scope Items by cost share:

item_share = (item_cost / total_in_scope_cost) × lump_sum_amount

Applied as an addition on top of the Item’s running cost — the underlying Item costs are not rewritten. The proportional distribution is recomputed if Rule scope or Item costs change.

3.5 No cross-rule dependencies

Each Rule sees only the running total; no Rule references another Rule. No conflict resolution. Linear stacking.

4. Submission Value derivation

Every Schedule Item gets a Submission Value (1:1 relationship). Non-Schedule Items do not.

Computation:

  1. Start with the Item’s total cost (derived from the Worksheet roll-up per Item spec §9).
  2. Run Rules in sequence_order. For each Rule that applies to this Item (via scope targets), add the Rule’s adjustment:
  • Percentage: (current_running_total_for_scope) × (rule_value / 100) × (this Item's share of scope) — distributed proportionally within scope
  • Lump Sum: (this Item's share of scope) × (rule_value)
  1. The final accumulated value is stored as computed_value on the Submission Value record.

Override: Lead Estimator can set override_value explicitly. When set, final_value = override_value; otherwise final_value = computed_value. Audit trail (updated_by, updated_at, optional audit_notes) is preserved.

Clearing an override: setting override_value = null reverts final_value to computed_value.

5. Commercials view interactions

5.1 Rules pane

  • Ordered list of Rules with name, type, value, scope summary, running state indicator.
  • Add Rule: modal or inline — name, type, value, scope targets (multi-select from the nine target types).
  • Reorder: drag. Changes final totals — UI should surface the recomputation clearly.
  • Edit scope: contextual scope picker with preview of affected Items count.
  • Delete: confirm modal listing which Items would lose the adjustment.

5.2 Totals pane

  • Running totals after each Rule — Direct, Indirect, Total, effective Margin.
  • Visual stack showing each Rule’s contribution to the total.

5.3 Submission Values pane

  • Per Schedule Item row: description, unit, quantity, computed value, override value (editable), final value, audit notes.
  • Override inline or via detail modal.
  • Jump-to-Item action → Estimate Editor scrolled to that Item.

6. Publisher view interactions

6.1 Preview

  • Rendered output of the submission artifact: branded header, cover letter, Schedule table, Submission Values (final), conditions, inclusions, exclusions.
  • Updates live as edits are made to the editor panels.

6.2 Editor panels

  • Cover letter — rich text; carries forward across republishes
  • Conditions — general terms (e.g., validity, GST treatment)
  • Inclusions / Exclusions — free text or Content Block references
  • Branding — from admin config (logo, colours, fonts)
  • File format — PDF / Excel (extensible)
  • Submit gate status — clean indicator or blocking-Item list

6.3 Publish action

The final Publish action runs the Submit gate:

ConditionAction
All Items are Priced / Reviewed / LockedPublish proceeds
Any Item is Unpriced or PluggedPublish blocked; a list of offending Items is surfaced with jump-to-Item actions

On successful Publish:

  • Publisher Output transitions Draft → Published.
  • schedule_snapshot captured — frozen JSON record of Schedule Item structure + Submission Values at publish time.
  • Estimate transitions Reviewed → Submitted (locked).
  • All Items cascade → Locked.
  • Tender transitions Active → Submitted (if this is the first publish on the Tender).
  • Any Adjudications on the Estimate are frozen.

Only the latest Publisher Output is retained per Estimate. Republishing generates a new Draft that, on Publish, replaces the prior Output.

6.4 Download

Download the latest Published artifact from the view.

7. Re-publish behaviour

The estimator can re-publish after Submit — though in practice this happens only via Admin unlock of the Estimate. On re-publish:

  • A new Publisher Output is opened in Draft state.
  • Cover letter, conditions, etc. carry forward from the prior Output.
  • Submit gate runs again.
  • On Publish, the prior Published artifact is replaced (latest only).

8. Validation & invariants

  1. Rule sequence_order unique within an Estimate.
  2. Rule value ≥ 0.
  3. Percentage Rule values typically 0–100 but not hard-capped.
  4. Submission Value 1:1 with Schedule Items — created atomically with the Item.
  5. final_value = override_value if set, else computed_value.
  6. Only the latest Publisher Output is retained per Estimate.
  7. Audit trail maintained on override writes.

9. Worked example

Three Rules stacking across an Estimate:

Estimate total cost (from Items): $100,000 direct

Rules (in sequence):
 1. Contingency 5% (Percentage, scope: Direct-only)
 +$5,000 → running $105,000
 2. Risk allowance $20K (Lump Sum, scope: All)
 +$20,000 → running $125,000 (distributed proportionally by cost share)
 3. Margin 8% (Percentage, scope: Direct-only)
 +$8,400 → 8% × $105K (current Direct running state after Rule 1)
 running $133,400

Submission Values:
 Per-Schedule-Item computation rolls up to $133,400 total
 Distributed to each Schedule Item by cost share
 Each value is editable as override

Publisher:
 Preview shows $133,400 schedule (or overridden values)
 Publish action runs Submit gate:
 if any Item Unpriced/Plugged → blocked
 else → Published, Estimate → Submitted, Items → Locked

Graph View