Telco BSS/OSS and TM Forum Alignment Case Study

1. Core Idea

Dalam telco/enterprise BSS/OSS, data model CPQ dan quote-to-cash harus bisa berdialog dengan konsep seperti:

• product catalog,
• product offering,
• product specification,
• quote,
• product order,
• product inventory,
• service order,
• service inventory,
• resource order,
• resource inventory,
• customer/account,
• agreement,
• billing account,
• trouble/fallout,
• usage/rating/billing.

TM Forum menyediakan reference model dan API pattern yang sangat berguna sebagai vocabulary dan interoperability guide.

Namun, alignment dengan TM Forum bukan berarti menyalin mentah semua resource menjadi internal schema.

Mental model:

Use TM Forum as canonical business vocabulary and integration contract inspiration, but protect internal domain invariants with bounded contexts, anti-corruption layers, snapshots, ownership, and production-specific constraints.

2. Why TM Forum Alignment Matters

TMF-style modelling membantu:

• standard vocabulary across telco systems,
• easier integration with BSS/OSS ecosystem,
• common structure for product catalog/order/inventory,
• related party modelling,
• characteristic modelling,
• external partner/API compatibility,
• consistency across quote/order/service/resource flows,
• onboarding engineers with industry concepts.

Tetapi risiko jika salah:

• internal model menjadi terlalu generic,
• domain invariant hilang di flexible characteristic bag,
• API resource dipakai langsung sebagai database entity,
• extensions tidak terdokumentasi,
• status mapping ambigu,
• product/service/resource boundary kabur,
• event/order decomposition tidak cocok dengan internal workflow,
• TMF reference dianggap "source-of-truth" tanpa ownership analysis.

3. BSS vs OSS Data Boundary

High-level distinction:

Typical flow:

Commercial Product Order
  -> Service Order
  -> Resource Order
  -> Network Provisioning
  -> Product/Service/Resource Inventory Update
  -> Billing Activation

Product is what customer buys.

Service is how it is technically delivered.

Resource is what physical/logical asset realizes the service.

4. Product vs Service vs Resource

This distinction is central.

Example:

Product Offering:
  Business Internet 500 Mbps

Product Instance:
  Customer A's Business Internet at Site Jakarta

Service Instance:
  Broadband access service / IP connectivity service

Resource Instance:
  port, VLAN, IP block, CPE device, circuit ID

Do not use product instance as a generic container for every technical detail.

5. TMF API Family Mapping

Common TMF API conceptual mapping:

Exact API usage, version, and internal mapping must be verified inside the team.

6. Product Catalog Alignment

TMF-style catalog typically models:

ProductCatalog
ProductCategory
ProductOffering
ProductSpecification
ProductOfferingPrice
ProductSpecificationCharacteristic
ProductOfferingTerm
BundledProductOffering

Internal CPQ needs additional production concerns:

• catalog publication lifecycle,
• effective dating,
• price list/version,
• compatibility rules,
• eligibility/serviceability,
• approval thresholds,
• orderability rules,
• decomposition rules,
• billing mapping,
• migration/deprecation,
• data governance.

TMF gives vocabulary. Internal model must preserve operational rules.

7. Product Offering vs Product Specification

Common alignment:

ProductOffering:
  commercial sellable package

ProductSpecification:
  describes product capabilities/structure

ProductOfferingPrice:
  pricing model/charge components

ProductSpecificationCharacteristic:
  configurable attributes

Internal anti-pattern:

Use product_offering_id everywhere and ignore product_spec/version/characteristics.

Better:

quote_item.product_offering_id
quote_item.product_offering_version
quote_item.product_specification_id
quote_item.configuration_snapshot
quote_item.price_snapshot

Order/product inventory should preserve accepted version.

8. Characteristic Modelling

TMF resources often use characteristic lists.

Example conceptual characteristic:

{
  "name": "bandwidth",
  "value": "500",
  "unitOfMeasure": "Mbps"
}

This flexible pattern is powerful.

But internal production model must decide:

• which characteristics are queryable,
• which are required,
• which affect price,
• which affect decomposition,
• which are sensitive,
• which need effective dating,
• which must be strongly typed,
• which need unit conversion.

Recommendation:

Use characteristic snapshot for contract evidence.
Extract critical/queryable/invariant fields into relational model.

9. Quote Alignment

TMF Quote concepts generally map to:

Quote
QuoteItem
ProductOfferingRef
ProductConfiguration
RelatedParty
QuotePrice
ValidityPeriod
State

Internal additions often needed:

• quote version/revision,
• pricing snapshot,
• approval evidence,
• margin/discount model,
• idempotency key,
• quote-to-order conversion status,
• audit trail,
• immutable acceptance snapshot,
• tenant/security classification,
• data lineage.

Do not let flexible quote payload bypass internal approval/pricing guards.

10. Product Order Alignment

TMF ProductOrder maps to enterprise order.

Core concepts:

ProductOrder
ProductOrderItem
OrderItemAction
ProductRefOrValue
RelatedParty
BillingAccountRef
OrderPrice
State

Internal production additions:

• source quote/version,
• order lifecycle vs fulfillment/billing status,
• idempotency key,
• decomposition run,
• state history,
• outbox/inbox,
• saga step,
• billing readiness,
• fallout/retry,
• reconciliation.

TMF ProductOrder is a contract boundary. Internal order model may be richer.

11. Order Item Action

Typical action values:

add
modify
delete / disconnect
noChange

Internal domain may need richer action semantics:

• suspend,
• resume,
• move,
• upgrade,
• downgrade,
• cancel,
• amend,
• reconnect,
• compensate,
• correct.

Mapping must be explicit:

external TMF action -> internal order_action_code

Do not overload modify to mean everything. It makes fulfillment and billing ambiguous.

12. Product Order to Service Order

Product order expresses customer/commercial intent.

Service order expresses technical fulfillment work.

Mapping:

ProductOrderItem
  -> DecompositionOutput
  -> ServiceOrder
  -> ServiceOrderItem
  -> ResourceOrder/Task

Need preserve:

• source product order item,
• decomposition rule version,
• target service spec,
• target resource spec,
• dependency,
• external OSS reference,
• status.

Service order should not lose commercial context.

13. Service Inventory Alignment

Service inventory records activated technical service.

Fields:

service_instance_id
product_instance_id
service_specification_id
status
service_characteristics
service_address/site
external_oss_service_id
activation_date
termination_date

Important relationships:

product_instance realizes service_instance
service_instance uses resource_instance
service_instance created from order_item/service_order_item

Service inventory is not the same as product inventory.

14. Resource Inventory Alignment

Resource inventory records assigned network/technical resources.

Examples:

• CPE device,
• SIM/ICCID/IMSI-like identifiers,
• IP block,
• VLAN,
• port,
• circuit,
• number,
• capacity allocation.

Resource data may be security-sensitive.

Important:

• resource lifecycle,
• reservation vs assignment,
• shared vs dedicated,
• effective dating,
• external OSS ownership,
• reconciliation with network system.

Do not expose resource inventory details broadly in customer-facing APIs.

15. Product Inventory Alignment

Product inventory is installed commercial truth.

Fields:

product_instance_id
product_offering_id/version
product_specification_id
customer/account
billing_account
status
start_date
termination_date
source_order_id
source_order_item_id
service_instance_refs
subscription/charge refs

TMF ProductInventory may expose product structure with nested product relationships.

Internal model must support:

• modify/disconnect,
• billing,
• reporting installed base,
• support traceability,
• entitlement,
• inventory reconciliation.

16. Customer, Party, and Account Alignment

TMF often uses party/relatedParty pattern.

Internal model should distinguish:

• party,
• individual,
• organization,
• customer,
• account,
• billing account,
• service account,
• contact,
• user/login.

Related party roles are useful:

buyer
payer
technicalContact
billingContact
installationContact
salesRep
approver

But roles must have governance and access control.

Do not use free-text role names without code set.

17. Agreement and Contract Alignment

Agreement/contract may apply to:

• pricing terms,
• product eligibility,
• commitment term,
• renewal,
• penalty,
• SLA,
• special discount,
• legal terms.

Internal model needs:

• agreement reference on quote/order/subscription,
• snapshot of applicable terms,
• effective dates,
• approval exceptions,
• billing impact,
• renewal/cancellation rules.

Agreement should not be just PDF attachment.

18. Billing Account Alignment

Billing account in quote/order/product inventory should be explicit.

Common flow:

quote.billing_account_id
  -> order.billing_account_id
  -> product_instance.billing_account_id
  -> charge.billing_account_id
  -> invoice.billing_account_id

Some fields are snapshots, some are active references.

Need define:

• source-of-truth,
• when billing account can change,
• how changes affect active products/charges,
• what happens to historical invoices,
• reconciliation rules.

19. Status Mapping

TMF status values may not exactly match internal lifecycle.

Example:

TMF ProductOrder.state = acknowledged/inProgress/completed/rejected/cancelled

Internal may have:

CAPTURED
VALIDATED
SUBMITTED
DECOMPOSED
IN_PROGRESS
PARTIALLY_FULFILLED
FULFILLED
COMPLETED
FALLOUT
FAILED
CANCELLED

Mapping must be explicit:

internal_status -> external_status
external_status -> internal_status
lossy_mapping flag

If mapping is lossy, do not use external status as internal source-of-truth.

20. Extension Strategy

TMF APIs allow extensions, but extension governance is critical.

Extension questions:

• Is extension field product-specific or generic?
• Is it temporary or permanent?
• Is it documented?
• Is it versioned?
• Is it sensitive?
• Does it affect billing/fulfillment?
• Should it be characteristic instead?
• Should it be first-class internal field?
• Are consumers aware?

Anti-pattern:

Put all internal production fields into @baseType/@type/extension blob.

Better:

• use extension sparingly,
• promote critical fields to governed contract,
• document extension schema,
• validate extension payload.

21. Anti-Corruption Layer

Internal model should be protected from external contract quirks.

Anti-corruption layer responsibilities:

• map external TMF payload to internal command,
• validate contract,
• normalize status/code/unit/time,
• map related parties,
• resolve references,
• enforce domain invariants,
• produce internal events,
• preserve external references.

Do not let external API payload directly mutate internal aggregate.

22. Canonical vs Internal Model

Canonical model can be useful for integration.

But internal bounded contexts may need specialized models.

Example:

Canonical ProductOrderResource
  useful for API/integration.

Internal Order Aggregate
  optimized for lifecycle, idempotency, decomposition, audit, performance.

A canonical model should not become a god model that every service must share as database entity.

23. Event Alignment

Events may use internal or canonical payload.

Options:

Often:

Internal event -> mapping/ACL -> external integration event

This protects internal evolution.

24. Reconciliation Across BSS/OSS

Critical reconciliation:

Product order item completed
  -> product instance active

Product instance active
  -> service instance active

Service instance active
  -> resource assigned

Product instance billable active
  -> recurring charge active

OSS active service
  -> BSS product/service inventory active

Billing active charge
  -> product instance active

BSS/OSS reconciliation is mandatory because systems have different sources and timing.

25. Example Crosswalk Table

26. PostgreSQL Illustrative Mapping Tables

Status mapping:

create table external_status_mapping (
  id uuid primary key,
  source_standard text not null,
  source_resource_type text not null,
  external_status text not null,
  internal_status_type text not null,
  internal_status text not null,
  lossy_mapping boolean not null default false,
  effective_from timestamptz not null,
  effective_to timestamptz
);

TMF extension registry:

create table api_extension_field_registry (
  id uuid primary key,
  api_name text not null,
  resource_type text not null,
  field_path text not null,
  field_name text not null,
  data_type text,
  owner_group text,
  data_classification text,
  required boolean not null default false,
  active boolean not null default true,
  documentation text
);

Product-service-resource realization:

create table product_service_resource_realization (
  id uuid primary key,
  product_instance_id uuid not null,
  service_instance_id uuid,
  resource_instance_id uuid,
  realization_type text not null,
  source_order_item_id uuid,
  effective_from timestamptz not null,
  effective_to timestamptz
);

27. Java/JAX-RS Backend Implications

API adapter/service layout:

TmfProductOrderResource
  -> TmfProductOrderMapper
  -> InternalCreateOrderCommand
  -> OrderApplicationService
  -> OrderAggregate/Repository
  -> Outbox

Important:

• mapping layer validates external payload,
• internal command uses internal vocabulary,
• domain service enforces invariants,
• response maps internal result back to TMF-style resource if needed.

Do not put business logic only in mapper.

28. Contract and Versioning Impact

TMF alignment needs contract discipline:

• API version,
• TMF version,
• extension version,
• code set mapping,
• unknown enum behavior,
• related party roles,
• characteristic typing,
• error model,
• partial update semantics,
• pagination/filtering behavior.

If internal model changes, external contract may remain stable through mapper.

If external contract changes, internal model should not be forced to change immediately.

29. Failure Modes

30. PR Review Checklist

When reviewing TMF/telco alignment changes, ask:

• Which TMF-style resource is involved?
• Is this external contract or internal domain model?
• Is anti-corruption mapping explicit?
• Are product/service/resource boundaries clear?
• Are related party roles governed?
• Are characteristics typed/validated where needed?
• Is product offering/spec/version preserved?
• Is order item action mapping explicit?
• Are status mappings documented and lossy mappings known?
• Are extensions registered and classified?
• Are external IDs source/tenant/environment scoped?
• Are BSS/OSS reconciliation rules updated?
• Are sensitive resource fields protected?
• Are contract tests updated?

31. Internal Verification Checklist

Verify these in the internal CSG/team context:

• Which TMF APIs/resources are actually used.
• Which TMF API versions/extensions are supported.
• Internal mapping for product catalog/quote/product order/product inventory.
• Whether service/resource inventory is internal or external OSS-owned.
• Whether service order/resource order objects exist internally.
• How relatedParty roles are governed.
• How characteristics are validated and typed.
• How internal statuses map to TMF-style states.
• How external callbacks map to internal entities.
• Whether anti-corruption layer exists.
• Whether BSS/OSS reconciliation is automated.
• Whether incidents mention TMF mapping mismatch, extension misuse, status confusion, or product/service/resource boundary ambiguity.

32. Summary

TM Forum alignment is valuable, but production systems need stronger internal modelling discipline.

A strong telco/TMF alignment model must define:

• BSS/OSS boundary,
• product/service/resource distinction,
• catalog/offering/spec/version mapping,
• quote/order/inventory mapping,
• order action mapping,
• product-to-service-to-resource realization,
• related party roles,
• billing account relationship,
• status mapping,
• extension governance,
• anti-corruption layer,
• event/contract versioning,
• cross-layer reconciliation,
• security classification.

The key principle:

Align with TM Forum for vocabulary and interoperability, but do not outsource your internal invariants, ownership, lifecycle, idempotency, reconciliation, and production correctness to a generic external resource model.