Order Action Model

1. Core Idea

Order action menjelaskan apa yang ingin dilakukan terhadap product/customer/service state.

Dalam enterprise CPQ / Order Management / Telco BSS/OSS, order item bukan hanya "line item". Ia membawa instruksi:

• tambah produk baru,
• modifikasi produk existing,
• disconnect layanan,
• suspend layanan,
• resume layanan,
• pindah lokasi,
• change plan,
• upgrade,
• downgrade,
• cancel order,
• amend order,
• koreksi data,
• retry atau compensate operation.

Action adalah dimensi data yang menentukan:

• validasi,
• required references,
• compatibility dengan product inventory,
• fulfillment path,
• billing impact,
• downstream event,
• audit evidence,
• allowed state transition,
• data reconciliation.

Mental model:

Order action is the semantic verb of an order item. Without a correct action model, the system cannot know whether an item creates, changes, suspends, resumes, terminates, or corrects a product/service relationship.

2. Why Action Modelling Matters

Kesalahan umum adalah memodelkan semua order item sebagai "produk yang dibeli".

Ini hanya cukup untuk order baru sederhana. Namun enterprise/telco order management harus mendukung lifecycle installed base:

• customer menambah add-on,
• customer upgrade bandwidth,
• customer downgrade package,
• customer pindah site,
• customer suspend sementara,
• customer resume setelah suspend,
• customer disconnect layanan,
• customer amend order sebelum completed,
• customer cancel order yang sedang fulfillment,
• system retry provisioning,
• support melakukan correction order,
• billing perlu tahu charge harus mulai, berhenti, prorate, atau berubah.

Tanpa action model yang eksplisit:

• modify bisa diproses sebagai add,
• disconnect bisa membuat duplicate termination,
• suspend tidak menghentikan billing sesuai policy,
• upgrade kehilangan relationship ke existing product,
• cancel order tidak membatalkan downstream task,
• billing tidak tahu apakah charge baru, stop, atau adjustment,
• reconciliation tidak bisa membedakan new sale vs churn vs migration.

3. Common Order Actions

Action aktual harus diverifikasi di sistem internal. Secara konseptual, action umum:

Action bisa dipakai di order item, fulfillment task, inventory effect, atau billing instruction. Jangan mencampur semua action di satu enum tanpa semantic boundary.

4. Action Is Not State

Action dan state sering tertukar.

Action menjawab:

Apa yang ingin dilakukan?

State menjawab:

Sudah sampai mana prosesnya?

Contoh:

action = DISCONNECT
state = IN_PROGRESS

Artinya disconnect sedang dieksekusi.

action = ADD
state = FALLOUT

Artinya add product gagal dalam fulfillment.

action = MODIFY
state = FULFILLED

Artinya perubahan product berhasil diterapkan.

Jangan membuat state seperti:

status = DISCONNECTING

kecuali state machine memang didesain begitu. Lebih bersih:

action = DISCONNECT
state = IN_PROGRESS

Dengan pemisahan ini, reporting dan rule menjadi lebih stabil.

5. Action and Product Inventory

Action hampir selalu bergantung pada current product inventory.

Critical invariant:

Order item action that affects an existing product must reference the target product instance.

Exceptions such as migration/correction must be explicit and audited.

6. Action and Billing

Action determines billing behavior.

Do not let billing infer everything from product status alone. Order action provides intent and timing.

7. Action and Fulfillment

Action also determines fulfillment path.

Examples:

Fulfillment decomposition should not infer action from textual product name. It should receive action as first-class data.

8. Action Validity Matrix

Action validity is contextual. It depends on current inventory state, product type, contract term, catalog rule, billing status, and order lifecycle.

Example matrix:

This matrix should not be hidden in scattered if statements. It should be documented and ideally centralized in policy code/rule data.

9. Action Compatibility with Catalog

Catalog may define which actions are allowed.

Examples:

• product offering is sellable for ADD,
• existing product can be upgraded to target offering,
• downgrade not allowed during contract lock-in,
• add-on can only be added if parent product active,
• feature can be suspended independently,
• disconnect requires minimum term completion or penalty,
• move allowed only for certain access technologies,
• product can be modified only for specific characteristics.

Data model should be able to reference:

• source offering/spec,
• target offering/spec,
• product relationship,
• compatibility rule version,
• eligibility rule result,
• reason for denial.

Potential conceptual table:

product_action_rule
- product_offering_id
- product_offering_version
- action
- target_product_offering_id
- allowed
- rule_version
- effective_from
- effective_to

Actual implementation may use rule engine, catalog service, or hard-coded policy. Verify internally.

10. Add Action

ADD creates a new product/service relationship.

Required data usually includes:

• product offering,
• product specification,
• configuration/characteristics,
• customer/account,
• billing account,
• site/location if serviceable,
• requested date,
• price/charge reference,
• source quote item,
• catalog version,
• fulfillment path.

Common invariants:

ADD order item must not reference an existing active product instance as target, unless this is migration/import/correction.
ADD order item must have price/charge reference if billable.
ADD serviceable product must have valid site/location.

Failure modes:

• duplicate product instance,
• billing starts before activation,
• missing service address,
• catalog version mismatch,
• add-on created without parent product.

11. Modify Action

MODIFY changes an existing product instance.

Required data usually includes:

• target product instance,
• current product version/status,
• delta configuration,
• effective date,
• reason,
• billing impact,
• fulfillment impact,
• compatibility validation.

Important design question:

Is modify modelled as full replacement snapshot or delta?

Options:

For complex systems, both can be useful:

• delta explains what changed,
• target snapshot supports fulfillment,
• current snapshot supports audit/reconciliation.

Failure modes:

• stale product instance modified,
• delta applied twice,
• billing not updated,
• old characteristic overwritten incorrectly,
• modification allowed during pending order.

12. Disconnect Action

DISCONNECT terminates product/service relationship.

Required data:

• target product instance,
• disconnect reason,
• requested disconnect date,
• effective termination date,
• billing stop instruction,
• resource release policy,
• contract/penalty awareness,
• customer notification/audit.

Common invariants:

DISCONNECT order item must reference active or suspend-eligible product instance.
DISCONNECT cannot complete unless resource/service deprovisioning is complete or explicitly bypassed.
Billing stop date must be derived from termination/activation policy, not arbitrary UI input.

Failure modes:

• product terminated but billing continues,
• billing stopped but service remains active,
• disconnect applied to wrong product instance,
• duplicate disconnect order,
• resources not released,
• early termination fee missed.

13. Suspend Action

SUSPEND temporarily disables product/service.

Required data:

• target product instance,
• suspension reason,
• suspension start date,
• expected resume date if applicable,
• billing policy,
• service disablement instruction,
• customer notification/audit.

Key question:

Does suspension stop billing, reduce billing, or keep billing unchanged?

Do not assume. It depends on product/commercial policy.

Failure modes:

• service suspended but billing continues incorrectly,
• billing paused but service still active,
• resume impossible due to missing suspension record,
• suspend applied to already suspended product,
• audit lacks reason.

14. Resume Action

RESUME reactivates suspended product/service.

Required data:

• suspended product instance,
• resume reason,
• resume effective date,
• billing resume policy,
• service enablement instruction,
• previous suspension reference.

Invariant:

RESUME requires target product instance status = SUSPENDED unless explicit repair/migration exception.

Failure modes:

• resume active product,
• billing resumes with wrong effective date,
• service enabled but inventory still suspended,
• previous suspension not linked.

15. Cancel Action

CANCEL usually applies to order/order item that is not completed.

Cancel is not the same as disconnect.

Examples:

• cancel installation before service active,
• cancel pending add order,
• cancel pending modify order,
• cancel unfulfilled item,
• cancel entire order.

Cancel needs to know fulfillment progress:

• not sent downstream: simple cancel,
• sent but not started: downstream cancel request,
• partially fulfilled: compensation may be required,
• completed: cancel no longer valid; use disconnect/reversal/correction.

Failure modes:

• cancel order but downstream continues,
• cancel item but billing trigger already fired,
• cancel completed item incorrectly,
• no cancellation reason/audit.

16. Amend Action

AMEND changes an order already submitted or in progress.

Amendment can be modelled as:

1. mutate original order/item,
2. create amendment order,
3. create delta order,
4. create revision/superseding order,
5. create compensation + new instruction.

For production systems, explicit delta/amendment model is safer than silently mutating original order.

Amendment must preserve:

• original order,
• amendment reason,
• changed items,
• added/removed/modified instructions,
• impact on fulfillment,
• impact on billing,
• approval if needed,
• audit trail,
• conflict detection.

Potential invariant:

In-flight order cannot be amended if affected item is already terminal unless amendment creates correction/compensation order.

17. Move Action

MOVE changes service location/site.

Move is often composite:

• disconnect/deactivate at old site,
• provision/activate at new site,
• preserve customer/account/product relationship,
• update serviceability,
• update address/tax/pricing,
• adjust billing,
• coordinate schedule.

Move may be modelled as its own action or as compound order:

MOVE =
  DISCONNECT old service leg
  ADD new service leg
  preserve product continuity

Do not choose blindly. Verify internal business semantics.

Failure modes:

• old site not disconnected,
• new site not activated,
• billing double charged,
• product inventory loses continuity,
• serviceability not checked for new site.

18. Change Plan, Upgrade, Downgrade

CHANGE_PLAN, UPGRADE, and DOWNGRADE affect product offering/spec and billing.

Questions:

• Is upgrade/downgrade just modify?
• Is target offering a successor?
• Is old product instance modified or superseded?
• Is new product instance created?
• Are charges prorated?
• Is customer under contract lock-in?
• Does change require approval?
• Does fulfillment require technical reprovisioning?

Possible inventory strategies:

Choose based on audit/billing/inventory requirements.

19. Correction, Retry, and Compensation

These are operational actions, not always customer-facing actions.

Be careful not to expose internal repair action as normal commercial action without audit.

Correction requires:

• incident or reason reference,
• actor authority,
• before/after snapshot,
• impacted entities,
• reconciliation evidence,
• approval if commercial/billing impact exists.

Retry requires:

• original attempt reference,
• idempotency,
• retry count,
• retry reason,
• external system response,
• DLQ/fallout handling.

Compensation requires:

• original effect,
• compensating effect,
• partial state,
• proof of reversal,
• downstream consistency.

20. Action Derivation from Quote

Quote item action may become order item action, but not always directly.

Examples:

Conversion should have explicit mapping rules.

Do not infer action from product name like "Upgrade Package".

21. Action and Idempotency

Action processing must be idempotent, especially for external integration and retry.

Idempotency examples:

• ADD must not create duplicate product instance on retry.
• DISCONNECT must not terminate twice or create duplicate final charges.
• SUSPEND retry should detect already suspended.
• RESUME retry should detect already active due to previous success.
• CHANGE_PLAN retry should not apply plan change twice.
• BILLING_TRIGGER should not create duplicate charge.

Data model support:

action_execution
- id
- order_item_id
- action
- idempotency_key
- execution_status
- target_entity_id
- external_reference
- attempt_count

22. Action Event Model

Action-specific events can be clearer than generic item update events.

Examples:

• ProductAddRequested
• ProductModifyRequested
• ProductDisconnectRequested
• ProductSuspendRequested
• ProductResumeRequested
• ProductMoveRequested
• ProductPlanChangeRequested
• OrderItemActionCompleted
• OrderItemActionFailed

Event payload should include:

{
  "eventId": "uuid",
  "eventType": "ProductDisconnectRequested",
  "eventVersion": 1,
  "occurredAt": "2026-07-12T10:00:00Z",
  "orderId": "order-id",
  "orderItemId": "order-item-id",
  "action": "DISCONNECT",
  "targetProductInstanceId": "product-instance-id",
  "requestedEffectiveDate": "2026-08-01",
  "reasonCode": "CUSTOMER_REQUEST",
  "correlationId": "corr-123"
}

Events must not leak sensitive pricing/customer data unless required by consumer contract.

23. PostgreSQL Modelling Considerations

23.1 Action as enum-like reference

Option:

create table order_action_reference (
  action_code text primary key,
  description text not null,
  affects_existing_product boolean not null,
  creates_product boolean not null,
  terminates_product boolean not null,
  billing_impact text,
  active boolean not null
);

This can document action semantics and support validation/reporting.

23.2 Order item fields

alter table product_order_item
add column action text not null,
add column target_product_instance_id uuid,
add column resulting_product_instance_id uuid,
add column action_reason_code text,
add column requested_effective_date date;

23.3 Action history

create table order_item_action_history (
  id uuid primary key,
  order_item_id uuid not null,
  action text not null,
  from_state text,
  to_state text,
  actor_id text,
  reason_code text,
  reason_text text,
  correlation_id text,
  occurred_at timestamptz not null
);

23.4 Useful constraints

Potential conceptual constraints:

-- Example only. Verify internal action values and exception policies.
alter table product_order_item
add constraint chk_existing_product_action_requires_target
check (
  action not in ('MODIFY', 'DISCONNECT', 'SUSPEND', 'RESUME', 'CHANGE_PLAN')
  or target_product_instance_id is not null
);

Be careful: migrations, corrections, and external orders may require exception path. If so, model exception explicitly rather than weakening all constraints.

24. Java/JAX-RS Implications

Action should be handled by command-specific services or command handlers.

Example API:

POST /orders/{orderId}/items/{itemId}/actions/validate
POST /orders/{orderId}/items/{itemId}/actions/start
POST /orders/{orderId}/items/{itemId}/actions/complete
POST /orders/{orderId}/items/{itemId}/actions/fail

For creating item:

{
  "action": "DISCONNECT",
  "targetProductInstanceId": "product-instance-id",
  "requestedEffectiveDate": "2026-08-01",
  "reasonCode": "CUSTOMER_REQUEST"
}

Application service should:

• validate action is supported,
• validate required references,
• validate product inventory status,
• validate catalog compatibility,
• validate billing impact,
• validate fulfillment path,
• write audit,
• publish action event,
• update order item state.

Avoid switch statements scattered across resource/controller/mapper. Centralize action policy.

25. MyBatis/JPA/JDBC Implications

MyBatis

Good for action validity queries:

• load target product instance,
• check pending orders for same product,
• check action history,
• check dependencies,
• update item state conditionally.

JPA

Be careful:

• action transitions should not be accidental entity mutations,
• action-specific invariant should live outside entity setters,
• optimistic locking required on order item and target inventory.

JDBC

Useful for deterministic action execution with explicit transaction.

Core rule:

Data access style must not bypass action policy.

26. Reporting and Analytics Impact

Action drives important metrics:

• new sales volume (ADD),
• churn/disconnect count (DISCONNECT),
• suspend/resume volume,
• upgrade/downgrade rate,
• modify order volume,
• plan change volume,
• move order volume,
• cancellation rate,
• amendment rate,
• action fallout rate,
• action cycle time,
• billing adjustment caused by action.

If action is missing or ambiguous, reporting cannot distinguish:

• new revenue vs existing revenue change,
• churn vs cancellation,
• suspension vs termination,
• upgrade vs modify,
• migration vs new sale.

27. Observability

Action-specific monitoring:

• ADD stuck before activation,
• DISCONNECT completed but billing still active,
• SUSPEND completed but service still active,
• RESUME completed but service still disabled,
• CHANGE_PLAN completed but price not updated,
• duplicate action for same product instance,
• pending action conflict,
• action failure by product type,
• fallout rate by action.

Example diagnostic query:

-- Existing-product actions without target instance
select id, order_id, action
from product_order_item
where action in ('MODIFY', 'DISCONNECT', 'SUSPEND', 'RESUME', 'CHANGE_PLAN')
  and target_product_instance_id is null;

-- Multiple active disconnect orders for same product instance
select target_product_instance_id, count(*)
from product_order_item
where action = 'DISCONNECT'
  and state not in ('CANCELLED', 'FULFILLED', 'FAILED')
group by target_product_instance_id
having count(*) > 1;

28. Failure Modes

29. PR Review Checklist

When reviewing action model changes, ask:

• What action is being introduced or changed?
• Is it customer-facing, operational, or repair-only?
• Does it require existing product instance?
• Does it create, modify, terminate, suspend, or resume inventory?
• What current product statuses allow this action?
• What catalog/product types support this action?
• Is action compatibility table/rule updated?
• What billing impact does the action have?
• What fulfillment path does the action trigger?
• Is action idempotent?
• Can duplicate action be created for same product instance?
• Does action require reason/audit?
• Does action affect order item state machine?
• Does action produce event?
• Does reporting need new classification?
• Does migration/backfill need default action?
• Are tests covering invalid action/current-state combinations?

30. Internal Verification Checklist

Verify these in the internal CSG/team context:

• Actual order item action enum.
• Whether action is stored on quote item, order item, fulfillment task, or all.
• Whether action semantics are documented.
• Whether action is confused with state in schema/API.
• Whether modify/disconnect/suspend/resume require product instance reference.
• Whether ADD can reference existing product during migration.
• Whether action compatibility is catalog-driven, rule-driven, or hard-coded.
• Whether pending action conflict detection exists.
• Whether billing impact is explicit per action.
• Whether fulfillment decomposition uses action.
• Whether action events exist.
• Whether action history/audit exists.
• Whether cancellation and disconnect are distinct in code and data.
• Whether amend is modelled as mutation, delta order, or revision.
• Whether move is modelled as native action or add/disconnect composition.
• Whether upgrade/downgrade are distinct or variants of change plan.
• Whether retry/correction/compensation are modelled and audited.
• Whether known incidents mention wrong action, duplicate disconnect, missing billing stop, or invalid modify.

31. Summary

Order action is the semantic verb of order execution.

A strong action model must define:

• action meaning,
• required references,
• allowed current inventory states,
• catalog compatibility,
• fulfillment path,
• billing impact,
• inventory effect,
• idempotency,
• audit evidence,
• event semantics,
• reporting classification,
• failure detection.

The key principle:

Never treat order action as a loose string. Treat it as a domain contract between quote, order, inventory, fulfillment, billing, and reporting.