Entity Instance and Configuration

EntityInstance and EntityInstanceConfiguration are the core runtime objects of tSM inventory.

• EntityInstance is stable identity (business key and type).
• EntityInstanceConfiguration is the time-aware runtime snapshot linked to a catalog specification.

This document starts with business semantics and then provides field-level references based on inventory public DTOs.

---

1. Business Meaning

1.1 What an Entity Instance Represents

An EntityInstance is a durable runtime identity for one real business/technical object, for example:

• one customer-facing service,
• one product subscription,
• one physical or logical resource.

Key intent:

• keep one stable identity across lifecycle changes,
• separate user-facing key (key) from internal UUID (id),
• maintain pointers to the currently effective and prepared-next configuration.

1.2 What an Entity Instance Configuration Represents

An EntityInstanceConfiguration is a versioned runtime state of an instance.

Key intent:

• bind runtime state to design-time definition (entityCatalogSpecificationId),
• store dynamic operational data in chars,
• capture time validity in validFor,
• support rollout states (CURRENT, PENDING, HISTORY, DRAFT).

1.3 Design-to-Run Anchor

A configuration cannot be modeled in isolation from design-time definitions:

• entityCatalogSpecificationId binds runtime to a catalog specification,
• relationship consistency is enforced through relationship identifiers in a dedicated entity (covered in next document).

This is the main mechanism that keeps catalog design and inventory runtime synchronized.

1.4 Timeline Semantics

tSM uses active to represent runtime timeline priority:

• CURRENT priority 0,
• PENDING priority 1,
• HISTORY priority 2,
• DRAFT priority 3.

Why CURRENT is first:

• most operational reads ask for the effective runtime state, not full historization,
• priority sorting can return the expected answer quickly without additional timeline logic,
• this supports practical queries like: "Give me the service, I do not mind historizations."

In other words, priority is an optimization for business-first retrieval of the active state.

Typical operational rule set:

1. one active current configuration per instance,
2. optional pending configuration for prepared changes,
3. older current versions become history after activation of pending.

1.4.1 Historization Timeline Example

Legend:

• done bar = HISTORY
• active bar = CURRENT
• crit bar = PENDING

Notes:

• 2025-09-17 is the modeled "today" split point in this example.
• "Open-end" validity is rendered as a long future date (2026-12-31) because Mermaid Gantt requires finite interval boundaries.

Detailed interpretation:

1. PRD-INET-001 - Internet Service

• One service instance with sequential versions.
• 20 Mbit/s and 40 Mbit/s are historical.
• 60 Mbit/s is the currently effective runtime version.
• 100 Mbit/s is prepared as pending future change.

2. RES-CPE-001 / DISC-001 - CPE and Discount

• Resource/cost lane linked to the same commercial context.
• Antenna remains active.
• Discount -300 ended and moved to history.

3. PRD-INET-001 - Wifi Branch

• Child branch under the same service context.
• Wifi and Extender are active branch components.

4. PRD-TV-001 - TV Service

• TV Basic is currently active runtime service line.
• Cancelled is pending termination intent, prepared but not yet cut over as final state.

How to read CURRENT and PENDING overlap:

• Overlap means next configuration is prepared while current remains effective.
• This supports controlled cutover windows and rollback-safe execution.
• Operational query "give me service now" returns CURRENT; planning/cutover query includes PENDING.

1.5 TM Forum Concept Mapping (High Level)

tSM entity	TMF concept alignment
EntityInstance + EntityInstanceConfiguration with type SERVICE	TMF638 Service
EntityInstance + EntityInstanceConfiguration with type PRODUCT	TMF637 Product
EntityInstance + EntityInstanceConfiguration with type RESOURCE	TMF639 Resource

TMF payload projection rules are documented in the dedicated TMF mapping page.

1.6 Why This Model Works

• preserves stable runtime identity,
• supports controlled future-dated changes,
• keeps dynamic attributes extensible without schema branching,
• allows one shared inventory engine for multiple runtime domains.

---

2. Structural Behavior and Rules

• EntityInstance.key is the readable ID for users and operators.
• EntityInstanceConfiguration.key and type are read-only mirrors from the linked instance.
• EntityInstanceConfiguration.status is governed by EntityInstanceConfigurationStatus code table.
• EntityInstanceConfiguration.parentEntityInstanceId models runtime tree parent linkage.

2.1 Current/Pending Pointer Behavior

EntityInstance has dedicated pointers:

• currentEntityInstanceConfigurationId,
• pendingEntityInstanceConfigurationId.

These pointers are a deliberate denormalization of the runtime model:

• they allow very fast "effective state" reads for UI/API use cases,
• they reduce the need to scan or sort all configurations during common operations.

The same result is still derivable without pointers by filtering configurations, for example:

• by entityInstanceId,
• by active = CURRENT (or PENDING),
• and optionally by validity interval.

So pointers optimize read-paths, while canonical history remains in configuration records.

2.2 Tree Query Behavior

Inventory client exposes a tree search (findTree) pattern that:

• starts from filtered nodes,
• climbs to active roots,
• returns active-filtered subtree.

This behavior is useful for service decomposition views and impact analysis.

2.3 TM Forum References

• TMF638 Service Inventory API directory
• TMF637 Product Inventory API directory
• TMF639 Resource Inventory API directory

---

3. Entity Reference: Entity Instance (EntityInstance)

Field	Type	Required	Read-only	Description
id	UUID	No	No	Internal primary key. Client may provide UUIDv4 or let tSM generate.
type	String	Yes	No	Inventory domain type (for example SERVICE, PRODUCT, RESOURCE).
key	String	No	No	Business-readable identifier shown to users.
dataTags	List<String>	No	No	Optional labels/tags.
currentEntityInstanceConfigurationId	UUID	No	No	Pointer to current configuration ID.
pendingEntityInstanceConfigurationId	UUID	No	No	Pointer to pending configuration ID.

3.1 Enum Reference: EntityInstanceActiveEnum

Value	Priority	Meaning
CURRENT	0	Effective runtime configuration.
PENDING	1	Prepared configuration waiting activation.
HISTORY	2	Historical superseded configuration.
DRAFT	3	Draft configuration state for preparation.

---

4. Entity Reference: Entity Instance Configuration (EntityInstanceConfiguration)

Field	Type	Required	Read-only	Description
id	UUID	No	No	Configuration primary key.
key	String	No	Yes	Derived from linked EntityInstance.key.
type	String	No	Yes	Derived from linked EntityInstance.type.
name	String	Yes	No	Human-readable configuration name.
status	String	Yes	No	Lifecycle status code (FK EntityInstanceConfigurationStatus.code).
customerId	UUID	No	No	Optional linked customer ID.
accountId	UUID	No	No	Optional linked account ID.
chars	TsmChars	No	No	Dynamic configuration attributes (JSON object).
crmAddress1Id	UUID	No	No	Optional CRM address 1.
crmAddress2Id	UUID	No	No	Optional CRM address 2.
active	EntityInstanceActiveEnum	No	No	Runtime timeline state (PENDING default).
dataTags	List<String>	No	No	Optional labels/tags.
entityCatalogSpecificationId	UUID	Yes	No	Design-time specification reference from catalog.
entityInstanceId	UUID	No	Yes	Linked instance ID (server-managed binding).
location1Id	String	No	No	Optional place/location reference 1.
location2Id	String	No	No	Optional place/location reference 2.
parentEntityInstanceId	UUID	No	No	Parent instance reference for runtime tree hierarchy.
validFor	TimePeriodAlt	No	No	Validity interval of this configuration.
entityInstance	EntityInstance	No	No	Expanded instance object when requested.
custom	Any	No	Yes	Additional read-only properties from indexed document.
keyNormalized	String	No	Yes	Optional normalized key for sorting/searching.
description	String	No	No	Configuration description.
whenInserted	Date	No	Yes	Legacy audit timestamp helper.
lifecycle	String	No	Yes	Lifecycle policy state (read-only).
removalTime	Date	No	No	Optional planned/recorded removal timestamp.

---

5. Status and Cost Governance

Status and cost are supporting models tightly connected to configuration lifecycle.

5.1 Status Governance

EntityInstanceConfigurationStatus is a configurable code table used by EntityInstanceConfiguration.status.

Important distinction:

• active (CURRENT, PENDING, HISTORY, DRAFT) controls timeline position,
• status (ACTIVE, CANCELLED, SUSPENDED, TERMINATED, and custom additions) controls business/operational lifecycle meaning.

This separation allows scenarios like:

• pending configuration with status ACTIVE prepared for activation date,
• current configuration with status SUSPENDED.

5.1.1 Entity Reference: EntityInstanceConfigurationStatus

Field	Type	Required	Read-only	Description
id	UUID	No	No	Status record primary key.
code	String	Yes	No	Technical status code (unique, API-safe identifier).
name	String	Yes	No	User-facing status label.
validityFrom	Date	No	No	Validity start.
validityTo	Date	No	No	Validity end.
description	String	No	No	Status description.
localizationData	LocalizationData	No	No	Localized labels and descriptions.
type	EntityInstanceConfigurationStatusTypeEnum	Yes	No	Coarse status type classification.
dataTags	List<String>	No	No	Optional labels/tags.
config	Map<String, Any?>	No	No	Additional status configuration payload.

5.1.2 Enum Reference: EntityInstanceConfigurationStatusTypeEnum

Value	Meaning
ACTIVE	Operationally active status family.
CANCELLED	Canceled state family.
SUSPENDED	Suspended state family.
TERMINATED	Terminated state family.

5.2 Cost Modeling

EntityInstanceConfigurationCost stores per-configuration cost records linked to catalog specification references.

Typical use:

• price snapshoting of runtime composition,
• cost breakdown per configuration item,
• feed for billing/revenue/cost analysis pipelines.

5.2.1 Entity Reference: EntityInstanceConfigurationCost

Field	Type	Required	Read-only	Description
id	UUID	No	No	Cost record primary key.
entityInstanceConfiguration	UUID	No	No	Linked configuration ID.
entityCatalogSpecificationId	UUID	Yes	No	Linked catalog specification ID.
quantity	Int	No	No	Quantity.
individualPrice	BigDecimal	No	No	Unit price value.
description	String	No	No	Optional tooltip/description.
lifecycle	String	No	Yes	Lifecycle policy state (read-only).
removalTime	Date	No	No	Optional removal timestamp.

5.2.2 Cost Example

{
  "entityInstanceConfiguration": "6fa0778f-d780-4d89-9c8f-95d4fd7b2f8d",
  "entityCatalogSpecificationId": "8bde2bfa-2de1-4775-9954-c48ef49ae89b",
  "quantity": 1,
  "individualPrice": 29.90,
  "description": "Monthly recurring charge for monitoring add-on"
}

5.2.3 Operational Recommendations

1. Keep status table business-owned and versioned with validity windows.
2. Treat active and status as separate dimensions in filters and dashboards.
3. Keep cost entries linked to the same catalog specification IDs used in configuration records.
4. Expose cost data through controlled APIs when financial consumers need runtime decomposition pricing.

---

6. Event Reference

EntityInstanceConfigurationCreateEventAfter is emitted after configuration creation and carries:

• entityInstanceConfigurationId,
• catalogSpecificationId.

Use this for asynchronous follow-up actions (for example orchestration kickoff, synchronization, enrichment).