Order Process Handling

This page describes runtime logic behind Ordering in tSM.

The page is intentionally process-focused and implementation-oriented. Model field reference is in Order Model Reference.

1. Processing Pipeline (High Level)

2. Service Provisioning and Fulfillment Steps

Service provisioning works over service-oriented (technical) execution scope and typically receives product intent as input that must be translated into service/resource actions.

Baseline steps commonly include:

1. validate order (including possible manual backoffice intervention),
2. verify service feasibility and availability,
3. decompose to RFS and derive required resources,
4. service design and resource-allocation requests to network/resource inventory,
5. service activation (automatic and/or manual),
6. field work planning and execution (often integrated with WFM skills/regions),
7. functional verification (manual and/or automated),
8. network and technical documentation updates.

tSM uses Process Engine capabilities for this lifecycle: process design, automatic action configuration, manual task assignment, and orchestration control.

3. Unified vs Split Ordering Model (BSS/OSS)

In telecom practice, two views exist:

• split model: Product Order (BSS) and Service Order (OSS) are distinct artifacts and often separate systems,
• unified model: one operational order contains both product and service sections.

tSM pragmatic approach:

1. ISP / small operator: one layer can be sufficient (product catalog + one order + one process).
2. Telco operator: product and service catalogs may be separated, but one provisioning order can still execute both scopes.
3. Tier-1 operator: full BSS/OSS split is often required (separate deployments, teams, SLAs/KPIs, and ownership boundaries). In this mode, product ordering can stay in one deployment while service-order execution runs in dedicated tsm-service-ordering. This microservice is a specialization of the general tsm-ordering service: it keeps the base order model/API contract and extends runtime behavior with service provisioning and activation methods. See Specialization pattern.

Even in unified order handling, separate product and service sections are recommended for decomposition quality, fulfillment control, and billing alignment.

4. Public API Behavioral Rules

Observed behavior in OrderPublicApiV2 and related services:

1. Update identity consistency: payload id is required, path key/ID and payload id must match, and key is immutable in update flow.
2. Person role consistency check: provided personRoleIds must belong to the given customer context.
3. Order line synchronization in update: persisted lines not present in incoming orderLines payload are deleted.
4. Process startup trigger: process startup is coupled with transition to IN_PROGRESS status.

5. Process Resolution Logic

When status is IN_PROGRESS, process code is resolved with this priority:

Reference sources in implementation:

• OrderProcessService.createProcess(order)
• OrderProcessService.findProcessCode(order)

6. Key Generation Logic

OrderService generates Order.key when missing:

1. if OrderType.mnemonicCode is set, evaluate mnemonic template,
2. otherwise fallback to sequence (ORD-...).

This keeps key generation configurable per installation while preserving a deterministic fallback.

7. Auto-Enrichment Logic

Before persistence, OrderService can auto-populate relation lists:

• crmAddressRoleIds from account/customer address roles,
• personRoleIds from account/customer person roles.

Feature toggles:

• tsm.entity.Order.addCustomerAddresses
• tsm.entity.Order.addCustomerPersonRoles

8. Process/Status Coupling Notes

• Order status codes are register-driven (OrderStatusPublic).
• Process engine behavior is not hardcoded to one universal lifecycle.
• IN_PROGRESS is the critical operational trigger in current implementation.

9. Current Boundaries

This document currently covers:

• runtime process trigger and resolution,
• validation and persistence side effects,
• enrichment and key generation mechanics.

Planned future enhancements can include:

• detailed status transition governance,
• retry and compensation patterns,
• event/notification contract mapping,
• deep integration playbooks (inventory, partner systems, billing).

10. Inventory Update Helper Logic

OrderProcessService.updateInventory(...) provides targeted inventory updates from ordering context:

1. iterate order lines,
2. select lines with entityInstanceConfigurationId,
3. load linked inventory configuration and its catalog specification,
4. if catalog code matches requested service catalog code, update specific characteristic path/value.

This utility is used for controlled synchronization from order-driven process steps to inventory configuration data.

11. Process Instance Control Helpers

Additional handling logic available in OrderProcessService:

• cancelAllActiveProcessInstances(businessKey, excludeProcessInstance) for coordinated cancellation patterns,
• getOrderProcess(orderId) to build process context/projection for order-centric runtime handling.

12. Activity and Calendar Coordination

During order handling, operators can create related activities/tasks and manage them through activity calendar capabilities.

This is useful for:

• scheduling manual checkpoints,
• synchronizing backoffice/field actions,
• tracking due dates outside purely automated process steps.