Skip to content

ABS ServicePlan: Contract Execution Architecture

Purpose: Define the integration contract between Odoo (commercial master) and ABS (execution engine) for asset-based service contracts.

Audience: System architects, integration developers, platform engineers implementing Odoo-ABS synchronization.

Overview

The architecture treats the Sales Order as the contract-of-record and ABS as the contract execution engine, with a clear, bidirectional contract state model.

1. Canonical Role Split

Odoo (Contract-of-Record)

Odoo asserts and persists the commercial truth:

  • What was contracted: sale.order + sale.order.line (goods + services)
  • Who it is with: res.partner
  • When it is in force: order status + line-level effective dates/terms
  • Which specific asset(s) are in scope: serial binding per line (your 1-to-1 rule)
  • Commercial amendments: replacements, upgrades, cancellations, renewals

Odoo's authoritative statement:

"There is a contract in force."

ABS (Execution-of-Record)

ABS asserts and persists the operational truth:

  • ServicePlan instances created from Odoo’s contract lines
  • Asset enforcement (IoT, swap gating, tracking service enablement)
  • Operational state and telemetry (“active”, “suspended”, “fault”, “violations”, “usage”)
  • Entitlement resolution (“this VIN can access this battery pool / station network”)

ABS's authoritative response:

"Yes—here are the details."

2. The Minimal Shared Contract Language

To make your statement operationally real, both sides must share a small set of stable identifiers and states.

Shared identifiers (non-negotiable)

  • contract_ref: Odoo sale.order (contract envelope)
  • contract_line_ref: Odoo sale.order.line (the contractual obligation)
  • asset_ref: Odoo stock.lot / serial number (the non-fungible asset identity)
  • customer_ref: Odoo res.partner

Shared lifecycle (two-layer state)

Layer A: Commercial validity (Odoo master)

  • Draft → Confirmed → In Force → Ended / Cancelled / Replaced

Layer B: Operational execution (ABS master)

  • Planned → Provisioned → Active → Suspended / Faulted → Terminated

This gives you the clean bidirectional statement:

  • Odoo: “Line X is In Force for Serial Y.”
  • ABS: “ServicePlan(X,Y) is Active, with these operational parameters and live status.”

3. Contract Validity Rules (Odoo-side)

To avoid ambiguity, “contract in force” should be a precise rule, typically:

A contract line is In Force when:

  1. The sale.order is confirmed (and optionally paid, depending on your policy), and
  2. The line has a valid serial binding (your 1-to-1 requirement), and
  3. The line’s effective period is active (start ≤ today ≤ end, if applicable)

This rule supports:

  • Sale + delivery
  • Rental (no sale of the asset, but contract still valid)
  • Privilege lines (no physical movement)

4. ABS Response Contract

Given contract_ref (sale.order) or contract_line_ref, ABS should be able to return:

  • ServicePlan list grouped by serial:

  • Serial: VIN123

    • WarrantyPlan: Active, ends 2027-01-01
    • SwapPrivilegePlan: Active, battery_class=UBP-48V, network=KE-Nairobi, limits=…
    • AntiTheftPlan: Suspended (no connectivity), last_seen=…
    • Enforcement posture:

  • Allowed / Denied / Conditional

  • Operational metrics:

  • Usage counters, exceptions, station events, etc.

This makes ABS the authoritative source for runtime truth while Odoo remains authoritative for commercial truth.

5. Integration Contract (Formalized)

Odoo is the commercial master record declaring which contract lines are valid for which serial-numbered assets; ABS is the execution master record implementing those contract lines as ServicePlans and reporting operational status back against the same identifiers.

6. Bundle Model Implementation

This supports your bundle logic cleanly:

  • A Sales Order can contain:

  • Goods line: Motorbike model (serial-bound)

  • Service lines: Warranty, Swap Privilege, Anti-theft (each serial-bound)
  • Rental/circulation lines: Battery issuance (serial-bound, different semantics)

Odoo does not require "the serial of the SO." The model requires serial-per-line binding.

Next Steps: Contract Mapping Specification

The integration implementation requires a Contract ↔ ServicePlan Mapping Spec defining:

  • Odoo object/field → ABS object/field mappings
  • Trigger events (create, amend, terminate)
  • Required invariants:
  • 1 line ↔ 1 serial
  • 1 serial ↔ many services
  • Contract validity propagation rules

This specification forms the foundation for integration development and operational procedures.