Configuration Relationships and Tree

Runtime structure in inventory uses two complementary link mechanisms:

• parent hierarchy on EntityInstanceConfiguration (parentEntityInstanceId),
• explicit cross-links on EntityInstanceConfigurationRelationship.

This mirrors catalog design while keeping runtime navigation fast and explicit.

Business Summary

• Parent-child relation models decomposition tree (main service and sub-services).
• Explicit relationship entity models non-hierarchical runtime links (depends-on, uses, option link, etc.).
• Explicit relationship points back to design-time relationship by entityCatalogSpecificationRelationshipId.

This keeps design-to-run consistency and supports runtime governance on relationship level.

---

1. Parent Hierarchy vs Explicit Relationship

1.1 Parent Hierarchy (parentEntityInstanceId)

Use when the business relation is strict structural containment.

Examples:

• internet service contains access service,
• product bundle contains product components,
• site service contains location-level sub-services.

1.2 Explicit Relationship (EntityInstanceConfigurationRelationship)

Use when relationship is not pure tree containment.

Examples:

• cross-link between services in different branches,
• optional add-on relation,
• dependency relation where both ends stay in separate trees.

1.3 Why Both Are Needed

• parent hierarchy gives efficient runtime tree rendering,
• explicit relationship preserves semantically important cross-links,
• both together represent full runtime topology without overloading one mechanism.

---

2. Relationship Entity Reference (EntityInstanceConfigurationRelationship)

Field	Type	Required	Read-only	Description
id	UUID	No	No	Relationship instance primary key.
entityInstanceConfigurationId	UUID	Yes	No	Source configuration ID (FK invt_ent_inst_conf.id).
entityInstanceToId	UUID	Yes	No	Target instance ID (FK invt_ent_inst.id).
entityCatalogSpecificationRelationshipId	UUID	Yes	No	Design-time catalog relationship reference.
chars	TsmChars	No	No	Dynamic relationship attributes.
data	Map<String, Any?>	No	No	Additional relationship payload.
lifecycle	String	No	Yes	Lifecycle policy state (read-only).
removalTime	Date	No	No	Optional removal timestamp.

---

3. Runtime Modeling Rules

1. Use parentEntityInstanceId for decomposition tree only.
2. Use explicit relationship entity for non-tree links.
3. Keep entityCatalogSpecificationRelationshipId set for every explicit runtime relation.
4. Put relation-level runtime metadata (for example socket or override flags) into relationship chars.

3.1 Example Relationship Payload

{
  "id": "8d3f4e23-6a5e-4ee1-b5fb-8ea8f08d2f7b",
  "entityInstanceConfigurationId": "6fa0778f-d780-4d89-9c8f-95d4fd7b2f8d",
  "entityInstanceToId": "670ab3e5-b8cf-44da-a6f0-e11f31f54ef8",
  "entityCatalogSpecificationRelationshipId": "cb4a4fab-4f93-44cb-860f-f3e078fc2137",
  "chars": {
    "relationshipType": "VAS",
    "socket": "ip-option"
  }
}

3.2 Tree and Cross-Link View

---

4. Query and Traversal Patterns

Typical operational patterns:

• get full subtree from selected root (service decomposition view),
• search subtree by active state filter (CURRENT, PENDING, ...),
• retrieve related configurations by explicit links for impact analysis.

The v2 client tree search pattern (/search-tree) supports these operations with filtering and active-state controls.

---

5. Mapping Notes to TMF

High-level conceptual alignment:

• TMF638 ServiceRelationship aligns to runtime explicit relationship semantics,
• TMF637 ProductRelationship aligns to product-domain explicit relationship semantics,
• TMF639 ResourceRelationship aligns to resource-domain explicit relationship semantics.

In tSM, all are normalized into EntityInstanceConfigurationRelationship plus type-specific projection logic.