From a91aeb598898c960b15155f1dade1bcd409aa8ca Mon Sep 17 00:00:00 2001 From: JvD_Ericsson Date: Wed, 28 May 2025 14:15:56 +0100 Subject: [PATCH] TEIV: update docs Issue-ID: SMO-188 Change-Id: I3cb812e53136cc9723cc2924d1287c18f679de0a Signed-off-by: JvD_Ericsson --- docs/_static/sample-entities.svg | 85 +++- docs/developer-guide.rst | 152 +++--- ...discover-and-reconciliation-interface-guide.rst | 235 +++++---- docs/discover-and-reconciliation-interface.rst | 565 +++++++++++---------- docs/groupings.rst | 47 +- docs/query-api-examples.rst | 52 +- docs/supported-filter-options.rst | 298 ++++++++--- 7 files changed, 864 insertions(+), 570 deletions(-) diff --git a/docs/_static/sample-entities.svg b/docs/_static/sample-entities.svg index f02a72a..ce009c5 100644 --- a/docs/_static/sample-entities.svg +++ b/docs/_static/sample-entities.svg @@ -1 +1,84 @@ -Sample Entities with AttributesOCUUPFunctionNRCellCUstring {key}id:uint32gNBId: uint32gNBIdLength:string {key}id:uint32cellLocalId: uint32nCI: uint32nRTAC:mcc: Mccmnc: MncpLMNId: \ No newline at end of file + + + + + + + + + + Sample + Entities + with + Attributes + + OCUUPFunction + + NRCellCU + + + + + + + string {key}​string[] + + + id:​sourceIds:​attributes: + + + + ​​uint32 + + + ​​ gNBId: + + + ​​uint32 + + + ​​ gNBIdLength: + + + string {key}​string[] + + + id:​sourceIds:​attributes: + + + ​​u + + + ​​int32 + + + ​​ cellLocalId: + + + ​​uint32 + + + ​​ nCI: + + + ​​uint32 + + + ​​ nRTAC: + + + mcc: + + Mcc + + mnc: + + Mnc + + pLMNId: + + + + + + \ No newline at end of file diff --git a/docs/developer-guide.rst b/docs/developer-guide.rst index 97cf75b..b64def7 100644 --- a/docs/developer-guide.rst +++ b/docs/developer-guide.rst @@ -1,6 +1,6 @@ .. This work is licensed under a Creative Commons Attribution 4.0 International License. .. SPDX-License-Identifier: CC-BY-4.0 -.. Copyright (C) 2024 Nordix Foundation. All rights Reserved +.. Copyright (C) 2024-2025 Nordix Foundation. All rights Reserved .. Copyright (C) 2024 OpenInfra Foundation Europe. All Rights Reserved Developer Guide @@ -15,51 +15,40 @@ topology and inventory data in your network. Introducing topology and inventory data ======================================= -Topology and inventory data is the information that represents entities -in a telecommunications network and the relationships between them that -provide insight into a particular aspect of the network of importance to -specific use cases. Topology and inventory data can be derived from -inventory, configuration, or other data. Topology & Inventory is being -updated autonomously based on changes in the network. +Topology and inventory data is the information that represents the entities +in a telecommunications network and the relationships between them. Topology +and inventory data can be derived from inventory and configuration. Topology +& Inventory is being updated autonomously based on changes in the network. Topology & Inventory supports several topology and inventory domains, see the :doc:`Data Models ` for -details on the topology and inventory model. The understanding of the -model is important to enable a user making queries on topology and -inventory data. The entities are modeled as managed objects (found under -the schema in the data dictionary) and grouped together in modules based -on functionality. See +details on the topology and inventory models. The understanding of the model +is important to enable a user making queries on topology and inventory data. +The entities are modeled as managed objects (under the schema in the data +dictionary) and grouped together in modules based on functionality. For +additional information, see :ref:`Supported domains ` -for the list of the topology and inventory domains currently supported -in Topology & Inventory capability. Concepts -------- -The building blocks of the Topology & Inventory are domains, entities, -and the relationships between each other. From a graph perspective, -entities are the vertices and relationships are the edges. These two -components are part of a subgraph, or the so-called domain. A -relationship can go beyond a single domain, since it can happen that the -two entities come from two separate ones. In this particular case, they -have a cross-domain relationship. +The building blocks of the Topology & Inventory are domains, entities, and +the relationships between each other. From a graph perspective, entities are +the vertices and relationships are the edges. These two components are part of +a subgraph, or the so-called domain. A relationship can be a cross-domain +relationship when its entities belong to different domains. Domain ~~~~~~ -A domain is a grouping of topology and inventory entities that handles -topology and inventory data. Topology and inventory data is the -information that represents entities in a telecommunications network and -the relationships between them that provides insight into a particular -aspect of the network of import to specific use cases. Topology and -inventory data can be derived from inventory, configuration, or other -data. Therefore, the topology and inventory model must define what the -telecoms network entities and relationships are. More information can be -found in :ref:`Supported domains `. -The Topology Exposure and Inventory Management (TEIV) domain is the -parent domain used for entities and relationships. This domain can be -used in reading and querying topology and inventory data when the domain -name of an entity or relationship is not known. +A domain is a grouping of topology and inventory entities that handles topology +and inventory data. The topology and inventory model defines what the telecoms +network entities and relationships are. More information can be found in +:ref:`Supported domains `. +The Topology Exposure and Inventory Management (TEIV) domain is the parent domain +used for entities and relationships. This domain can be used in reading and querying +topology and inventory data when the domain name of an entity or relationship is not +known. Entity ~~~~~~ @@ -84,23 +73,6 @@ have one or multiple relationships which can be defined by the user. A possible relationship between ManagedElement and ODUFunction can be *MANAGEDELEMENT_MANAGES_ODUFUNCTION*. -Consumer Data -~~~~~~~~~~~~~ - -Consumer data is data that enriches Topology & Inventory models. It can be -attached to topology entity or topology relation instance, outside of the -declared topology entity or topology relationship attributes. - -Three types of consumer data are supported: - -- Source IDs (read only) -- Classifiers (read and write) -- Decorators (read and write) - -For information about how consumer data relates to the Topology & Inventory model -and how this information is encoded, see -:doc:`Topology & Inventory Data Models ` - Topology identifiers ~~~~~~~~~~~~~~~~~~~~ @@ -115,24 +87,17 @@ Topology & Inventory. Apps must rely on `sourceIds` which is a list that contains the URN prefixed source identifiers of a topology object. -Metadata and reliability Indicator -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Metadata provides additional information about entities and relationships within the -database. - -The **reliabilityIndicator** is used to indicate the status of the topology data -within the network. See the -:doc:`Common YANG Types ` -in the Topology & Inventory Data Models for more information. It is implemented as a name-value -pair within the metadata column. It applies to every entity and relationship. - -Values for **reliabilityIndicator**: - -1. **RESTORED**: The data was restored from a backup and the responsible adapters are checking to ensure that the data is current. -2. **OK**: The data is in alignment with the source of truth, as far as Topology Exposure Handling is aware. -3. **ADVISED**: Entity implicitly created by Topology & Inventory Exposure Handling and potentially not aligned with the source of truth. +Understanding identifiers +^^^^^^^^^^^^^^^^^^^^^^^^^ +Source IDs is a list which contains the URN prefixed FDNs of a topology entity. It +contains one or more entries (number of entries can be dependent on the vendor) +- Entities that can be derived directly from CM. These entities have only one instance + of "`urn:3gpp:dn:`" within the sourceIds list. Examples of these are the ODUFunction + and NRCellDU instances. +- Composite entities that cannot be derived directly from CM. These entities have + multiple instances of "`urn:3gpp:dn:`" within the sourceIds list. An example of these + entities are the AntennaModule instances. Topology & Inventory models --------------------------- @@ -164,6 +129,41 @@ NRCellDU has direct relationships with ODUFunction and NRSectorCarrier, while it also has indirect relationships with ManagedElement, AntennaCapability, and AntennaModule. +Consumer Data +~~~~~~~~~~~~~ + +Consumer data is data that enriches Topology & Inventory models. It can be +attached to topology entity or topology relation instance, outside of the +declared topology entity or topology relationship attributes. + +Three types of consumer data are supported: + +- Source IDs (read only) +- Classifiers (read and write) +- Decorators (read and write) + +For information about how consumer data relates to the Topology & Inventory model +and how this information is encoded, see +:doc:`Topology & Inventory Data Models ` + +Metadata and reliability Indicator +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Metadata provides additional information about entities and relationships within the +database. + +The **reliabilityIndicator** is used to indicate the status of the topology data +within the network. See the +:doc:`Common YANG Types ` +in the Topology & Inventory Data Models for more information. It is implemented as a name-value +pair within the metadata column. It applies to every entity and relationship. + +Values for **reliabilityIndicator**: + +1. **RESTORED**: The data was restored from a backup and the responsible adapters are checking to ensure that the data is current. +2. **OK**: The data is in alignment with the source of truth, as far as Topology Exposure Handling is aware. +3. **ADVISED**: Entity implicitly created by Topology & Inventory Exposure Handling and potentially not aligned with the source of truth. + Supported domains ----------------- @@ -183,7 +183,7 @@ Supported domains | | | example, tilt, max power, and so on. | +-----------------------------------+-------------------------------------------------------+ | OAM | | This model contains the topology entities and | -| | | relations in the O&M domain, which are intended | +| | | relations in the OAM domain, which are intended | | | | to represent management systems and management | | | | interfaces. | +-----------------------------------+-------------------------------------------------------+ @@ -192,15 +192,23 @@ Supported domains | | | comprises cloud infrastructure and deployment | | | | aspects that can be used in the topology model. | +-----------------------------------+-------------------------------------------------------+ +| PHYSICAL | | This model contains the topology entities and | +| | | relations in the Physical domain, which is | +| | | modeled to understand the physical appliances and | +| | | locations to be used in the topology model. | ++-----------------------------------+-------------------------------------------------------+ | REL_EQUIPMENT_RAN | | This model contains the topology relations | | | | between Equipment and RAN. | +-----------------------------------+-------------------------------------------------------+ | REL_OAM_RAN | | This model contains the topology relations | -| | | between O&M and RAN. | +| | | between OAM and RAN. | +-----------------------------------+-------------------------------------------------------+ -| REL_CLOUD_RAN | | This model contains the RAN Cloud to RAN Logical | +| REL_CLOUD_RAN | | This model contains the Cloud to RAN Logical | | | | topology relations. | +-----------------------------------+-------------------------------------------------------+ -| REL_OAM_CLOUD | | This model contains the RAN O&M to Cloud | +| REL_OAM_CLOUD | | This model contains the OAM to Cloud | | | | topology relations. | +-----------------------------------+-------------------------------------------------------+ +| REL_PHYSICAL_RAN | | This model contains the topology relationship | +| | | between the physical domain and the RAN domain. | ++-----------------------------------+-------------------------------------------------------+ diff --git a/docs/discover-and-reconciliation-interface-guide.rst b/docs/discover-and-reconciliation-interface-guide.rst index 5565dc9..df9321c 100644 --- a/docs/discover-and-reconciliation-interface-guide.rst +++ b/docs/discover-and-reconciliation-interface-guide.rst @@ -1,6 +1,6 @@ .. This work is licensed under a Creative Commons Attribution 4.0 International License. .. SPDX-License-Identifier: CC-BY-4.0 -.. Copyright (C) 2024 Nordix Foundation. All rights Reserved +.. Copyright (C) 2024-2025 Nordix Foundation. All rights Reserved .. Copyright (C) 2024 OpenInfra Foundation Europe. All Rights Reserved Discover and Reconciliation Interface Guide @@ -77,61 +77,63 @@ Payload: .. code:: json { - "entities": [ - { - "o-ran-smo-teiv-equipment:Site": [ - { - "id": "urn:o-ran:smo:teiv:sha512:Site=1F137533843657E9E9DBE60DBD86B045A057DB6D04B6A07AC153", - "attributes": { - "name": "Dublin", - "geo-location": { - "latitude": 41.73297, - "longitude": -73.007696 - } - }, + "entities": [ + { + "o-ran-smo-teiv-equipment:Site": [ + { + "id": "urn:o-ran:smo:teiv:sha512:Site=8864DE35AF8F7552810308401DE712AD07877BBA7568860029BCECD3667F7A9D6DF5DFDA72BF475E5153BBE3035AAC229AD63DECC539C541B45598509088DB4E", + "attributes": { + "name": "Dublin", + "geo-location": { + "latitude": 41.73297, + "longitude": -73.007696 + } + }, "sourceIds": [ - "urn:oran:smo:teiv:Site=1" + "urn:oran:smo:teiv:atoll:Site=1" ] - } - ] - }, - { - "o-ran-smo-teiv-equipment:AntennaModule": [ - { - "id": "urn:o-ran:smo:teiv:sha512:AntennaModule=1FEBF137533843657E9E9DBE60DBD86B045A057DB6D04B6A07AC15323F1906228E93CFA4A1DB37D50252B3AFE6AEC9860E2CEA4A77BB3A25C9EA45DEDA87E765", - "attributes": { - "geo-location": { - "latitude": 41.73297, - "longitude": -73.007696 - }, - "sourceIds": [ - "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaUnit=1", - "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaUnit=1,AntennaSubunit=1", - "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaNearUnit=1,RetSubUnit=1" - ] - } - } - ] - } - ], - "relationships": [ - { - "o-ran-smo-teiv-equipment:ANTENNAMODULE_INSTALLED_AT_SITE": [ - { - "id": "urn:o-ran:smo:teiv:sha512:ANTENNAMODULE_INSTALLED_AT_SITE=TlJDZWxsRFU6U3ViTmV0d29yaz1FdXJvcGUsU3ViTmV0d29yaz1JcmVs=", - "aSide": "urn:o-ran:smo:teiv:sha512:AntennaModule=1FEBF137533843657E9E9DBE60DBD86B045A057DB6D04B6A07AC15323F1906228E93CFA4A1DB37D50252B3AFE6AEC9860E2CEA4A77BB3A25C9EA45DEDA87E765", - "bSide": "urn:o-ran:smo:teiv:sha512:Site=1F137533843657E9E9DBE60DBD86B045A057DB6D04B6A07AC153", + } + ] + }, + { + "o-ran-smo-teiv-equipment:AntennaModule": [ + { + "id": "urn:o-ran:smo:teiv:sha512:AntennaModule=1FEBF137533843657E9E9DBE60DBD86B045A057DB6D04B6A07AC15323F1906228E93CFA4A1DB37D50252B3AFE6AEC9860E2CEA4A77BB3A25C9EA45DEDA87E765", + "attributes": { + "geo-location": { + "latitude": 41.73297, + "longitude": -73.007696 + } + }, + "sourceIds": [ + "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaUnit=1", + "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaUnit=1,AntennaSubunit=1", + "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaNearUnit=1,RetSubUnit=1", + "urn:cmHandle:72538B1D598FA5A901D945A187D5542A" + ] + } + ] + } + ], + "relationships": [ + { + "o-ran-smo-teiv-equipment:ANTENNAMODULE_INSTALLED_AT_SITE": [ + { + "id": "urn:o-ran:smo:teiv:sha512:ANTENNAMODULE_INSTALLED_AT_SITE=E725018642FCC6D9BD7EB846DF31F080B878420A9C5E002CFB39F2AAEB6D3D66E655A132DB0852C6984B2052ABB62B1815A9C802A35ED865F8992328F1144C25", + "aSide": "urn:o-ran:smo:teiv:sha512:AntennaModule=1FEBF137533843657E9E9DBE60DBD86B045A057DB6D04B6A07AC15323F1906228E93CFA4A1DB37D50252B3AFE6AEC9860E2CEA4A77BB3A25C9EA45DEDA87E765", + "bSide": "urn:o-ran:smo:teiv:sha512:Site=8864DE35AF8F7552810308401DE712AD07877BBA7568860029BCECD3667F7A9D6DF5DFDA72BF475E5153BBE3035AAC229AD63DECC539C541B45598509088DB4E", "sourceIds": [ "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaUnit=1", "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaUnit=1,AntennaSubunit=1", "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaNearUnit=1,RetSubUnit=1", - "urn:oran:smo:teiv:Site=1" + "urn:cmHandle:72538B1D598FA5A901D945A187D5542A", + "urn:oran:smo:teiv:atoll:Site=1" ] - } - ] - } - ] - } + } + ] + } + ] + } Example of modify enriched Topology & Inventory with geographical data ---------------------------------------------------------------------- @@ -159,62 +161,64 @@ Payload: .. code:: json - { - "entities": [ - { - "o-ran-smo-teiv-equipment:Site": [ - { - "id": "urn:o-ran:smo:teiv:sha512:Site=1F137533843657E9E9DBE60DBD86B045A057DB6D04B6A07AC153", - "attributes": { - "name": "Dublin", - "geo-location": { - "latitude": 52.73297, - "longitude": -84.007696 - } - }, - "sourceIds": [ - "urn:oran:smo:teiv:atoll:Site=1" - ] - } - ] - }, - { - "o-ran-smo-teiv-equipment:AntennaModule": [ - { - "id": "urn:o-ran:smo:teiv:sha512:AntennaModule=1FEBF137533843657E9E9DBE60DBD86B045A057DB6D04B6A07AC15323F1906228E93CFA4A1DB37D50252B3AFE6AEC9860E2CEA4A77BB3A25C9EA45DEDA87E765", - "attributes": { - "geo-location": { - "latitude": 52.73297, - "longitude": -84.007696 - }, + { + "entities": [ + { + "o-ran-smo-teiv-equipment:Site": [ + { + "id": "urn:o-ran:smo:teiv:sha512:Site=8864DE35AF8F7552810308401DE712AD07877BBA7568860029BCECD3667F7A9D6DF5DFDA72BF475E5153BBE3035AAC229AD63DECC539C541B45598509088DB4E", + "attributes": { + "name": "Dublin", + "geo-location": { + "latitude": 52.73297, + "longitude": -84.007696 + } + }, "sourceIds": [ - "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaUnit=1", - "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaUnit=1,AntennaSubunit=1", - "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaNearUnit=1,RetSubUnit=1" + "urn:oran:smo:teiv:atoll:Site=1" ] - } - } - ] - } - ], - "relationships": [ - { - "o-ran-smo-teiv-equipment:ANTENNAMODULE_INSTALLED_AT_SITE": [ - { - "id": "urn:o-ran:smo:teiv:sha512:ANTENNAMODULE_INSTALLED_AT_SITE=TlJDZWxsRFU6U3ViTmV0d29yaz1FdXJvcGUsU3ViTmV0d29yaz1JcmVs=", - "aSide": "urn:o-ran:smo:teiv:sha512:AntennaModule=1FEBF137533843657E9E9DBE60DBD86B045A057DB6D04B6A07AC15323F1906228E93CFA4A1DB37D50252B3AFE6AEC9860E2CEA4A77BB3A25C9EA45DEDA87E765", - "bSide": "urn:o-ran:smo:teiv:sha512:Site=1F137533843657E9E9DBE60DBD86B045A057DB6D04B6A07AC153", - "sourceIds": [ - "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaUnit=1", - "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaUnit=1,AntennaSubunit=1", - "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaNearUnit=1,RetSubUnit=1", - "urn:oran:smo:teiv:atoll:Site=1" - ] - } - ] - } - ] - } + } + ] + }, + { + "o-ran-smo-teiv-equipment:AntennaModule": [ + { + "id": "urn:o-ran:smo:teiv:sha512:AntennaModule=3FF03633DCCAF1C44409FA0D0D3C32F00635DDAD5363A5E175A04A4AE5125641FCC6D727801275E8E6879AFB6D342B3E9473CC1307A702E41389882ECB513C8A", + "attributes": { + "geo-location": { + "latitude": 52.73297, + "longitude": -84.007696 + } + }, + "sourceIds": [ + "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaUnit=2", + "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaUnit=2,AntennaSubunit=1", + "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaNearUnit=2,RetSubUnit=1", + "urn:cmHandle:72538B1D598FA5A901D945A187D5542A" + ] + } + ] + } + ], + "relationships": [ + { + "o-ran-smo-teiv-equipment:ANTENNAMODULE_INSTALLED_AT_SITE": [ + { + "id": "urn:o-ran:smo:teiv:sha512:ANTENNAMODULE_INSTALLED_AT_SITE=3F3C6E552965769E31FB0E25FE805A25981B47A50AE3115BE5C74EB018866D79524A4D30D92E30EF547A3208CA8F88041136608319826B577C66E63A1CB0AA82", + "aSide": "urn:o-ran:smo:teiv:sha512:AntennaModule=3FF03633DCCAF1C44409FA0D0D3C32F00635DDAD5363A5E175A04A4AE5125641FCC6D727801275E8E6879AFB6D342B3E9473CC1307A702E41389882ECB513C8A", + "bSide": "urn:o-ran:smo:teiv:sha512:Site=8864DE35AF8F7552810308401DE712AD07877BBA7568860029BCECD3667F7A9D6DF5DFDA72BF475E5153BBE3035AAC229AD63DECC539C541B45598509088DB4E", + "sourceIds": [ + "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaUnit=2", + "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaUnit=2,AntennaSubunit=1", + "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaNearUnit=2,RetSubUnit=1", + "urn:cmHandle:72538B1D598FA5A901D945A187D5542A", + "urn:oran:smo:teiv:atoll:Site=1" + ] + } + ] + } + ] + } Example of delete enriched data from Topology & Inventory --------------------------------------------------------- @@ -243,35 +247,26 @@ Payload: .. code:: json - { + { "entities" : [ { "o-ran-smo-teiv-equipment:Site": [ - { - "id": "urn:o-ran:smo:teiv:sha512:Site=1F137533843657E9E9DBE60DBD86B045A057DB6D04B6A07AC153", - "sourceIds": [ - "urn:oran:smo:teiv:atoll:Site=1" - ] - } + { + "id": "urn:o-ran:smo:teiv:sha512:Site=8864DE35AF8F7552810308401DE712AD07877BBA7568860029BCECD3667F7A9D6DF5DFDA72BF475E5153BBE3035AAC229AD63DECC539C541B45598509088DB4E" + } ] } ], "relationships": [ { "o-ran-smo-teiv-equipment:ANTENNAMODULE_INSTALLED_AT_SITE": [ - { - "id" : "urn:o-ran:smo:teiv:sha512:ANTENNAMODULE_INSTALLED_AT_SITE=TlJDZWxsRFU6U3ViTmV0d29yaz1FdXJvcGUsU3ViTmV0d29yaz1JcmVs=", - "sourceIds": [ - "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaUnit=2", - "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaUnit=2,AntennaSubunit=1", - "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaNearUnit=2,RetSubUnit=1", - "urn:oran:smo:teiv:atoll:Site=1" - ] - } + { + "id" : "urn:o-ran:smo:teiv:sha512:ANTENNAMODULE_INSTALLED_AT_SITE=3F3C6E552965769E31FB0E25FE805A25981B47A50AE3115BE5C74EB018866D79524A4D30D92E30EF547A3208CA8F88041136608319826B577C66E63A1CB0AA82" + } ] } ] - } + } How to create and produce an event ================================== diff --git a/docs/discover-and-reconciliation-interface.rst b/docs/discover-and-reconciliation-interface.rst index 4f4e788..aec3be1 100644 --- a/docs/discover-and-reconciliation-interface.rst +++ b/docs/discover-and-reconciliation-interface.rst @@ -1,6 +1,6 @@ .. This work is licensed under a Creative Commons Attribution 4.0 International License. .. SPDX-License-Identifier: CC-BY-4.0 -.. Copyright (C) 2024 Nordix Foundation. All rights Reserved +.. Copyright (C) 2024-2025 Nordix Foundation. All rights Reserved .. Copyright (C) 2024 OpenInfra Foundation Europe. All Rights Reserved Discover and Reconciliation Interface @@ -42,8 +42,14 @@ CREATE Headers +----------------+--------+-------------------------------------------+--------------------------+-----------------+-------------------+ | ce_id | string | Unique identifier for the event. | - | - | - | +----------------+--------+-------------------------------------------+--------------------------+-----------------+-------------------+ -| ce_source | string | Source of the CloudEvent. | - | | format | - | -| | | | | | (`uri`) | | +| ce_source | string | Source of the CloudEvent. | | template ("adapterId( | | format | | This is a | +| | | | | {namespace}- | | (`uri`) | | template for | +| | | | | {nameOverride})") | | | the adapterId | +| | | | | | | structure. An | +| | | | | | | example is | +| | | | | | | "dmi-2-oss-ran- | +| | | | | | | topology- | +| | | | | | | adapter" | +----------------+--------+-------------------------------------------+--------------------------+-----------------+-------------------+ | ce_type | string | | Event type. It can be one of | - | - | - | | | | | topology-inventory-ingestion.merge, | | | | @@ -113,108 +119,118 @@ CREATE Payload .. code:: json - { - "entities": [ - { - "o-ran-smo-teiv-equipment:AntennaModule": [ - { - "id": "urn:oran:smo:teiv:AntennaModule=1", - "attributes": { - "antennaModelNumber": "1", - "mechanicalAntennaBearing": 50, - "mechanicalAntennaTilt": 10, - "positionWithinSector": "Unknown", - "totalTilt": 14, - "electricalAntennaTilt": 2, - "antennaBeamWidth": [ - 35, - 23, - 21 - ], - "geo-location": { - "latitude": 41.73297, - "longitude": -73.007696, - "height": 3000 - } - }, - "sourceIds": [ - "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaUnit=1", - "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaUnit=1,AntennaSubunit=1", - "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaNearUnit=1,RetSubUnit=1" - ], - "metadata": { - "reliabilityIndicator": "OK" - } - } - ] - }, - { - "o-ran-smo-teiv-equipment:AntennaModule": [ - { - "id": "urn:oran:smo:teiv:AntennaModule=2", - "attributes": { - "antennaModelNumber": "2", - "mechanicalAntennaBearing": 61, - "mechanicalAntennaTilt": 21, - "positionWithinSector": "Unknown", - "totalTilt": 25, - "electricalAntennaTilt": 3, - "antennaBeamWidth": [ - 46, - 34, - 32 - ], - "geo-location": { - "latitude": 52.84308, - "longitude": -84.118707, - "height": 41111 - } - }, - "sourceIds": [ - "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaUnit=2", - "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaUnit=2,AntennaSubunit=1", - "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaNearUnit=2,RetSubUnit=1" - ], - "metadata": { - "reliabilityIndicator": "OK" - } - } - ] - } - ], - "relationships": [ - { - "o-ran-smo-teiv-equipment:ANTENNAMODULE_INSTALLED_AT_SITE": [ - { - "id": "urn:sha512:TlJDZWxsRFU6U3ViTmV0d29yaz1FdXJvcGUsU3ViTmV0d29yaz1JcmVs=", - "aSide": "urn:oran:smo:teiv:AntennaModule=1", - "bSide": "urn:oran:smo:teiv:Site=1", - "sourceIds": [ - "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaUnit=1", - "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaUnit=1,AntennaSubunit=1", - "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaNearUnit=1,RetSubUnit=1", - "urn:oran:smo:teiv:Site=1" - ] - } - ] - }, - { - "o-ran-smo-teiv-equipment:ANTENNAMODULE_INSTALLED_AT_SITE": [ - { - "id": "urn:sha512:TlJDZWxsRFU6U3ViTmV0d29yaz1FdXJvcGUsU3ViTmV0d29yaz1JcmVsYW5kLE1lQ2=", - "aSide": "urn:oran:smo:teiv:AntennaModule=2", - "bSide": "urn:oran:smo:teiv:Site=2", - "sourceIds": [ - "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaUnit=2", - "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaUnit=2,AntennaSubunit=1", - "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaNearUnit=2,RetSubUnit=1", - "urn:oran:smo:teiv:Site=2" - ] - } - ] - } - ] - } + { + "entities": [ + { + "o-ran-smo-teiv-equipment:Site": [ + { + "id": "urn:o-ran:smo:teiv:sha512:Site=8864DE35AF8F7552810308401DE712AD07877BBA7568860029BCECD3667F7A9D6DF5DFDA72BF475E5153BBE3035AAC229AD63DECC539C541B45598509088DB4E", + "attributes": { + "name": "Dublin", + "geo-location": { + "latitude": 41.73297, + "longitude": -73.007696 + } + }, + "sourceIds": [ + "urn:oran:smo:teiv:atoll:Site=1" + ] + } + ] + }, + { + "o-ran-smo-teiv-equipment:Site": [ + { + "id": "urn:o-ran:smo:teiv:sha512:Site=32fedd82fd4a6d1c21ab68eb35c725fdd4ffcca963ea17e90775c9608829b03655d2133238df83334f7824bef4230292f97653b4a426847daa55005162e7c697", + "attributes": { + "name": "Dublin", + "geo-location": { + "latitude": 41.73297, + "longitude": -73.007696 + } + }, + "sourceIds": [ + "urn:oran:smo:teiv:atoll:Site=2" + ] + } + ] + }, + { + "o-ran-smo-teiv-equipment:AntennaModule": [ + { + "id": "urn:oran:smo:teiv:sha512:AntennaModule=1FEBF137533843657E9E9DBE60DBD86B045A057DB6D04B6A07AC15323F1906228E93CFA4A1DB37D50252B3AFE6AEC9860E2CEA4A77BB3A25C9EA45DEDA87E765", + "attributes": { + "geo-location": { + "latitude": 41.73297, + "longitude": -73.007696, + "height": 3000 + } + }, + "sourceIds": [ + "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaUnit=1", + "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaUnit=1,AntennaSubunit=1", + "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaNearUnit=1,RetSubUnit=1", + "urn:cmHandle:72538B1D598FA5A901D945A187D5542A" + ] + } + ] + }, + { + "o-ran-smo-teiv-equipment:AntennaModule": [ + { + "id": "urn:oran:smo:teiv:sha512:AntennaModule=3FF03633DCCAF1C44409FA0D0D3C32F00635DDAD5363A5E175A04A4AE5125641FCC6D727801275E8E6879AFB6D342B3E9473CC1307A702E41389882ECB513C8A", + "attributes": { + "geo-location": { + "latitude": 52.84308, + "longitude": -84.118707, + "height": 41111 + } + }, + "sourceIds": [ + "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaUnit=2", + "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaUnit=2,AntennaSubunit=1", + "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaNearUnit=2,RetSubUnit=1", + "urn:cmHandle:72538B1D598FA5A901D945A187D5542A" + ] + } + ] + } + ], + "relationships": [ + { + "o-ran-smo-teiv-equipment:ANTENNAMODULE_INSTALLED_AT_SITE": [ + { + "id": "urn:o-ran:smo:teiv:sha512:ANTENNAMODULE_INSTALLED_AT_SITE=E725018642FCC6D9BD7EB846DF31F080B878420A9C5E002CFB39F2AAEB6D3D66E655A132DB0852C6984B2052ABB62B1815A9C802A35ED865F8992328F1144C25", + "aSide": "urn:oran:smo:teiv:sha512:AntennaModule=1FEBF137533843657E9E9DBE60DBD86B045A057DB6D04B6A07AC15323F1906228E93CFA4A1DB37D50252B3AFE6AEC9860E2CEA4A77BB3A25C9EA45DEDA87E765", + "bSide": "urn:oran:smo:teiv:sha512:Site=8864DE35AF8F7552810308401DE712AD07877BBA7568860029BCECD3667F7A9D6DF5DFDA72BF475E5153BBE3035AAC229AD63DECC539C541B45598509088DB4E", + "sourceIds": [ + "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaUnit=1", + "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaUnit=1,AntennaSubunit=1", + "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaNearUnit=1,RetSubUnit=1", + "urn:cmHandle:72538B1D598FA5A901D945A187D5542A", + "urn:oran:smo:teiv:atoll:Site=1" + ] + } + ] + }, + { + "o-ran-smo-teiv-equipment:ANTENNAMODULE_INSTALLED_AT_SITE": [ + { + "id": "urn:o-ran:smo:teiv:sha512:ANTENNAMODULE_INSTALLED_AT_SITE=3262e72478e8ee8cc26c62600ecd93ad917c3d6bcc4db8e7baa14dd1ecc8dff0c660b28bbd93c55bb71de4ebc5a10e32ea2d40147e24a086b2e57556f4552170", + "aSide": "urn:oran:smo:teiv:sha512:AntennaModule=3FF03633DCCAF1C44409FA0D0D3C32F00635DDAD5363A5E175A04A4AE5125641FCC6D727801275E8E6879AFB6D342B3E9473CC1307A702E41389882ECB513C8A", + "bSide": "urn:oran:smo:teiv:sha512:Site=32fedd82fd4a6d1c21ab68eb35c725fdd4ffcca963ea17e90775c9608829b03655d2133238df83334f7824bef4230292f97653b4a426847daa55005162e7c697", + "sourceIds": [ + "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaUnit=2", + "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaUnit=2,AntennaSubunit=1", + "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaNearUnit=2,RetSubUnit=1", + "urn:cmHandle:72538B1D598FA5A901D945A187D5542A", + "urn:oran:smo:teiv:atoll:Site=2" + ] + } + ] + } + ] + } .. _Ingestion Merge: @@ -247,8 +263,14 @@ MERGE Headers +----------------+--------+-------------------------------------------+--------------------------+-----------------+-------------------+ | ce_id | string | Unique identifier for the event. | - | - | - | +----------------+--------+-------------------------------------------+--------------------------+-----------------+-------------------+ -| ce_source | string | Source of the CloudEvent. | - | | format | - | -| | | | | | (`uri`) | | +| ce_source | string | Source of the CloudEvent. | | template ("adapterId( | | format | | This is a | +| | | | | {namespace}- | | (`uri`) | | template for | +| | | | | {nameOverride})") | | | the adapterId | +| | | | | | | structure. An | +| | | | | | | example is | +| | | | | | | "dmi-2-oss-ran- | +| | | | | | | topology- | +| | | | | | | adapter" | +----------------+--------+-------------------------------------------+--------------------------+-----------------+-------------------+ | ce_type | string | | Event type. It can be one of | - | - | - | | | | | topology-inventory-ingestion.merge, | | | | @@ -321,108 +343,119 @@ MERGE Payload .. code:: json - { - "entities": [ - { - "o-ran-smo-teiv-equipment:AntennaModule": [ - { - "id": "urn:oran:smo:teiv:AntennaModule=1", - "attributes": { - "antennaModelNumber": "1", - "mechanicalAntennaBearing": 50, - "mechanicalAntennaTilt": 10, - "positionWithinSector": "Unknown", - "totalTilt": 14, - "electricalAntennaTilt": 2, - "antennaBeamWidth": [ - 35, - 23, - 21 - ], - "geo-location": { - "latitude": 41.73297, - "longitude": -73.007696, - "height": 3000 - } - }, - "sourceIds": [ - "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaUnit=1", - "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaUnit=1,AntennaSubunit=1", - "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaNearUnit=1,RetSubUnit=1" - ], - "metadata": { - "reliabilityIndicator": "OK" - } - } - ] - }, - { - "o-ran-smo-teiv-equipment:AntennaModule": [ - { - "id": "urn:oran:smo:teiv:AntennaModule=2", - "attributes": { - "antennaModelNumber": "2", - "mechanicalAntennaBearing": 61, - "mechanicalAntennaTilt": 21, - "positionWithinSector": "Unknown", - "totalTilt": 25, - "electricalAntennaTilt": 3, - "antennaBeamWidth": [ - 46, - 34, - 32 - ], - "geo-location": { - "latitude": 52.84308, - "longitude": -84.118707, - "height": 41111 - } - }, - "sourceIds": [ - "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaUnit=2", - "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaUnit=2,AntennaSubunit=1", - "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaNearUnit=2,RetSubUnit=1" - ], - "metadata": { - "reliabilityIndicator": "OK" - } - } - ] - } - ], - "relationships": [ - { - "o-ran-smo-teiv-equipment:ANTENNAMODULE_INSTALLED_AT_SITE": [ - { - "id": "urn:sha512:TlJDZWxsRFU6U3ViTmV0d29yaz1FdXJvcGUsU3ViTmV0d29yaz1JcmVs=", - "aSide": "urn:oran:smo:teiv:AntennaModule=1", - "bSide": "urn:oran:smo:teiv:Site=1", - "sourceIds": [ - "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaUnit=1", - "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaUnit=1,AntennaSubunit=1", - "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaNearUnit=1,RetSubUnit=1", - "urn:oran:smo:teiv:Site=1" - ] - } - ] - }, - { - "o-ran-smo-teiv-equipment:ANTENNAMODULE_INSTALLED_AT_SITE": [ - { - "id": "urn:sha512:TlJDZWxsRFU6U3ViTmV0d29yaz1FdXJvcGUsU3ViTmV0d29yaz1JcmVsYW5kLE1lQ2=", - "aSide": "urn:oran:smo:teiv:AntennaModule=2", - "bSide": "urn:oran:smo:teiv:Site=2", - "sourceIds": [ - "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaUnit=2", - "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaUnit=2,AntennaSubunit=1", - "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaNearUnit=2,RetSubUnit=1", - "urn:oran:smo:teiv:Site=2" - ] - } - ] - } - ] - } + + { + "entities": [ + { + "o-ran-smo-teiv-equipment:Site": [ + { + "id": "urn:o-ran:smo:teiv:sha512:Site=8864DE35AF8F7552810308401DE712AD07877BBA7568860029BCECD3667F7A9D6DF5DFDA72BF475E5153BBE3035AAC229AD63DECC539C541B45598509088DB4E", + "attributes": { + "name": "Dublin", + "geo-location": { + "latitude": 41.73297, + "longitude": -73.007696 + } + }, + "sourceIds": [ + "urn:oran:smo:teiv:atoll:Site=1" + ] + } + ] + }, + { + "o-ran-smo-teiv-equipment:Site": [ + { + "id": "urn:o-ran:smo:teiv:sha512:Site=32fedd82fd4a6d1c21ab68eb35c725fdd4ffcca963ea17e90775c9608829b03655d2133238df83334f7824bef4230292f97653b4a426847daa55005162e7c697", + "attributes": { + "name": "Dublin", + "geo-location": { + "latitude": 41.73297, + "longitude": -73.007696 + } + }, + "sourceIds": [ + "urn:oran:smo:teiv:atoll:Site=2" + ] + } + ] + }, + { + "o-ran-smo-teiv-equipment:AntennaModule": [ + { + "id": "urn:oran:smo:teiv:sha512:AntennaModule=1FEBF137533843657E9E9DBE60DBD86B045A057DB6D04B6A07AC15323F1906228E93CFA4A1DB37D50252B3AFE6AEC9860E2CEA4A77BB3A25C9EA45DEDA87E765", + "attributes": { + "geo-location": { + "latitude": 41.73289, + "longitude": -73.007687, + "height": 3000 + } + }, + "sourceIds": [ + "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaUnit=1", + "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaUnit=1,AntennaSubunit=1", + "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaNearUnit=1,RetSubUnit=1", + "urn:cmHandle:72538B1D598FA5A901D945A187D5542A" + ] + } + ] + }, + { + "o-ran-smo-teiv-equipment:AntennaModule": [ + { + "id": "urn:oran:smo:teiv:sha512:AntennaModule=3FF03633DCCAF1C44409FA0D0D3C32F00635DDAD5363A5E175A04A4AE5125641FCC6D727801275E8E6879AFB6D342B3E9473CC1307A702E41389882ECB513C8A", + "attributes": { + "geo-location": { + "latitude": 52.84398, + "longitude": -84.118776, + "height": 41111 + } + }, + "sourceIds": [ + "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaUnit=2", + "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaUnit=2,AntennaSubunit=1", + "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaNearUnit=2,RetSubUnit=1", + "urn:cmHandle:72538B1D598FA5A901D945A187D5542A" + ] + } + ] + } + ], + "relationships": [ + { + "o-ran-smo-teiv-equipment:ANTENNAMODULE_INSTALLED_AT_SITE": [ + { + "id": "urn:o-ran:smo:teiv:sha512:ANTENNAMODULE_INSTALLED_AT_SITE=E725018642FCC6D9BD7EB846DF31F080B878420A9C5E002CFB39F2AAEB6D3D66E655A132DB0852C6984B2052ABB62B1815A9C802A35ED865F8992328F1144C25", + "aSide": "urn:oran:smo:teiv:sha512:AntennaModule=1FEBF137533843657E9E9DBE60DBD86B045A057DB6D04B6A07AC15323F1906228E93CFA4A1DB37D50252B3AFE6AEC9860E2CEA4A77BB3A25C9EA45DEDA87E765", + "bSide": "urn:oran:smo:teiv:sha512:Site=8864DE35AF8F7552810308401DE712AD07877BBA7568860029BCECD3667F7A9D6DF5DFDA72BF475E5153BBE3035AAC229AD63DECC539C541B45598509088DB4E", + "sourceIds": [ + "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaUnit=1", + "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaUnit=1,AntennaSubunit=1", + "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaNearUnit=1,RetSubUnit=1", + "urn:cmHandle:72538B1D598FA5A901D945A187D5542A", + "urn:oran:smo:teiv:atoll:Site=1" + ] + } + ] + }, + { + "o-ran-smo-teiv-equipment:ANTENNAMODULE_INSTALLED_AT_SITE": [ + { + "id": "urn:o-ran:smo:teiv:sha512:urn:sha512:ANTENNAMODULE_INSTALLED_AT_SITE=3262e72478e8ee8cc26c62600ecd93ad917c3d6bcc4db8e7baa14dd1ecc8dff0c660b28bbd93c55bb71de4ebc5a10e32ea2d40147e24a086b2e57556f4552170", + "aSide": "urn:oran:smo:teiv:sha512:AntennaModule=3FF03633DCCAF1C44409FA0D0D3C32F00635DDAD5363A5E175A04A4AE5125641FCC6D727801275E8E6879AFB6D342B3E9473CC1307A702E41389882ECB513C8A", + "bSide": "urn:oran:smo:teiv:sha512:Site=32fedd82fd4a6d1c21ab68eb35c725fdd4ffcca963ea17e90775c9608829b03655d2133238df83334f7824bef4230292f97653b4a426847daa55005162e7c697", + "sourceIds": [ + "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaUnit=2", + "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaUnit=2,AntennaSubunit=1", + "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaNearUnit=2,RetSubUnit=1", + "urn:cmHandle:72538B1D598FA5A901D945A187D5542A", + "urn:oran:smo:teiv:atoll:Site=2" + ] + } + ] + } + ] + } .. _Ingestion Delete: @@ -455,8 +488,14 @@ DELETE Headers +----------------+--------+-------------------------------------------+--------------------------+-----------------+-------------------+ | ce_id | string | Unique identifier for the event. | - | - | - | +----------------+--------+-------------------------------------------+--------------------------+-----------------+-------------------+ -| ce_source | string | Source of the CloudEvent. | - | | format | - | -| | | | | | (`uri`) | | +| ce_source | string | Source of the CloudEvent. | | template ("adapterId( | | format | | This is a | +| | | | | {namespace}- | | (`uri`) | | template for | +| | | | | {nameOverride})") | | | the adapterId | +| | | | | | | structure. An | +| | | | | | | example is | +| | | | | | | "dmi-2-oss-ran- | +| | | | | | | topology- | +| | | | | | | adapter" | +----------------+--------+-------------------------------------------+--------------------------+-----------------+-------------------+ | ce_type | string | | Event type. It can be one of | - | - | - | | | | | topology-inventory-ingestion.merge, | | | | @@ -529,60 +568,50 @@ DELETE Payload .. code:: json { - "data": { - "entities": [ - { - "o-ran-smo-teiv-equipment:AntennaModule": [ - { - "id": "urn:oran:smo:teiv:AntennaModule=1", - "sourceIds": [ - "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaUnit=1", - "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaUnit=1,AntennaSubunit=1", - "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaNearUnit=1,RetSubUnit=1" - ] - } - ] - }, - { - "o-ran-smo-teiv-equipment:AntennaModule": [ - { - "id": "urn:oran:smo:teiv:AntennaModule=2", - "sourceIds": [ - "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaUnit=2", - "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaUnit=2,AntennaSubunit=1", - "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaNearUnit=2,RetSubUnit=1" - ] - } - ] - } - ], - "relationships": [ - { - "o-ran-smo-teiv-equipment:ANTENNAMODULE_INSTALLED_AT_SITE": [ - { - "id": "urn:sha512:TlJDZWxsRFU6U3ViTmV0d29yaz1FdXJvcGUsU3ViTmV0d29yaz1JcmVs=", - "sourceIds": [ - "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaUnit=1", - "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaUnit=1,AntennaSubunit=1", - "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaNearUnit=1,RetSubUnit=1", - "urn:oran:smo:teiv:Site=1" - ] - } - ] - }, - { - "o-ran-smo-teiv-equipment:ANTENNAMODULE_INSTALLED_AT_SITE": [ - { - "id": "urn:sha512:TlJDZWxsRFU6U3ViTmV0d29yaz1FdXJvcGUsU3ViTmV0d29yaz1JcmVsYW5kLE1lQ2=", - "sourceIds": [ - "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaUnit=2", - "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaUnit=2,AntennaSubunit=1", - "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaNearUnit=2,RetSubUnit=1", - "urn:oran:smo:teiv:Site=2" - ] - } - ] - } - ] - } - } \ No newline at end of file + "entities": [ + { + "o-ran-smo-teiv-equipment:Site": [ + { + "id": "urn:o-ran:smo:teiv:sha512:Site=8864DE35AF8F7552810308401DE712AD07877BBA7568860029BCECD3667F7A9D6DF5DFDA72BF475E5153BBE3035AAC229AD63DECC539C541B45598509088DB4E" + } + ] + }, + { + "o-ran-smo-teiv-equipment:Site": [ + { + "id": "urn:o-ran:smo:teiv:sha512:Site=32fedd82fd4a6d1c21ab68eb35c725fdd4ffcca963ea17e90775c9608829b03655d2133238df83334f7824bef4230292f97653b4a426847daa55005162e7c697" + } + ] + }, + { + "o-ran-smo-teiv-equipment:AntennaModule": [ + { + "id": "urn:oran:smo:teiv:AntennaModule=1FEBF137533843657E9E9DBE60DBD86B045A057DB6D04B6A07AC15323F1906228E93CFA4A1DB37D50252B3AFE6AEC9860E2CEA4A77BB3A25C9EA45DEDA87E765" + } + ] + }, + { + "o-ran-smo-teiv-equipment:AntennaModule": [ + { + "id": "urn:oran:smo:teiv:AntennaModule=3FF03633DCCAF1C44409FA0D0D3C32F00635DDAD5363A5E175A04A4AE5125641FCC6D727801275E8E6879AFB6D342B3E9473CC1307A702E41389882ECB513C8A" + } + ] + } + ], + "relationships": [ + { + "o-ran-smo-teiv-equipment:ANTENNAMODULE_INSTALLED_AT_SITE": [ + { + "id": "urn:sha512:ANTENNAMODULE_INSTALLED_AT_SITE=E725018642FCC6D9BD7EB846DF31F080B878420A9C5E002CFB39F2AAEB6D3D66E655A132DB0852C6984B2052ABB62B1815A9C802A35ED865F8992328F1144C25" + } + ] + }, + { + "o-ran-smo-teiv-equipment:ANTENNAMODULE_INSTALLED_AT_SITE": [ + { + "id": "urn:sha512:ANTENNAMODULE_INSTALLED_AT_SITE=3262e72478e8ee8cc26c62600ecd93ad917c3d6bcc4db8e7baa14dd1ecc8dff0c660b28bbd93c55bb71de4ebc5a10e32ea2d40147e24a086b2e57556f4552170" + } + ] + } + ] + } \ No newline at end of file diff --git a/docs/groupings.rst b/docs/groupings.rst index ef008f7..8ef13e0 100644 --- a/docs/groupings.rst +++ b/docs/groupings.rst @@ -1,6 +1,6 @@ .. This work is licensed under a Creative Commons Attribution 4.0 International License. .. SPDX-License-Identifier: CC-BY-4.0 -.. Copyright (C) 2024 Nordix Foundation. All rights Reserved +.. Copyright (C) 2024-2025 Nordix Foundation. All rights Reserved .. Copyright (C) 2024 OpenInfra Foundation Europe. All Rights Reserved Topology grouping @@ -54,6 +54,14 @@ when creating static groups. | providedMembers | | A list containing the identities of the | True | | | | desired members (entities or | | | | | relationships) in the model format. | | +| | | Only topology modules, entities types, | | +| | | and relationships types present in the | | +| | | Topology & Inventory models are accepted. | | +| | | The IDs of the desired members must be in | | +| | | the Uniform Resource Name (URN) format | | +| | | and must start with urn:. The IDs that do | | +| | | not exist in topology, can also be added | | +| | | here. | | +-----------------+---------------------------------------------+--------------+ **Example:** Create a static group with two provided members: @@ -119,25 +127,38 @@ when creating dynamic groups. | | | members that are returned when the dynamic | | | | | group is resolved. | | +-------------------------------+------------------------------------------------+--------------------------------------------------+ -| criteria.queryType | | This is the type of query that is performed | True | -| | | when resolving a topology group. Use one of | | -| | | the following query types when creating a | | -| | | dynamic group: | | -| | |
  • getEntitiesByDomain
    • | | -| | |
  • getEntitiesByType
    • | | -| | |
  • getRelationshipsForEntityId
    • | | -| | |
  • getRelationshipsByType
| | +| criteria.queryType | | The type of query performed when resolving a | True | +| | | topology group. Each query type belongs to a | | +| | | Topology & Inventory API endpoint. A | | +| | | detailed description about each query type | | +| | | can be found in its corresponding Topology & | | +| | | Inventory API. The following is the mapping | | +| | | of supported query type to its Topology & | | +| | | Inventory API: | | +| | | | | +| | | : | | +| | | getEntitiesByDomain: Get entities by domain. | | +| | | getEntitiesByType: Get entities by domain. | | +| | | getRelationshipsForEntityId: Get entities by | | +| | | domain. | | +| | | getRelationshipsByType: Get entities by | | +| | | domain. | | +-------------------------------+------------------------------------------------+--------------------------------------------------+ -| criteria.domain | | This is the topology domain. Use TEIV if not | True | -| | | known. | | +| criteria.domain | | Topology domain. Accepted domains include | True | +| | | only those present in the Topology & | | +| | | Inventory models. More information can be | | +| | | found in Supported domains. Use TEIV if not | | +| | | known. It is recommended to use TEIV domain | | +| | | in combination with targetFilter and | | +| | | scopeFilter for best performance. | | +-------------------------------+------------------------------------------------+--------------------------------------------------+ | criteria.entityTypeName | The entity type, for example, `OCUCPFunction` | | Required only when *criteria.queryType* is | | | | | `getEntitiesByType` or | | | | | `getRelationshipsForEntityId` | +-------------------------------+------------------------------------------------+--------------------------------------------------+ | criteria.entityId | | The entity identifier, for example, urn: | | Required only when *criteria.queryType* is | -| | | 3gpp: dn :ManagedElement=1,ODUFunction=1, | | `getRelationshipsForEntityId` | -| | | NRCellDU=1. | | +| | | `3gpp:dn:ManagedElement=1,ODUFunction=1,` | | `getRelationshipsForEntityId` | +| | | `NRCellDU=1.` | | +-------------------------------+------------------------------------------------+--------------------------------------------------+ | criteria.relationshipTypeName | | The relationship type, for example, | | Required only when *criteria.queryType* is | | | | `ODUFUNCTION_PROVIDES_NRCELLDU`. | | `getRelationshipsByType` | diff --git a/docs/query-api-examples.rst b/docs/query-api-examples.rst index 319b647..a95d53b 100644 --- a/docs/query-api-examples.rst +++ b/docs/query-api-examples.rst @@ -1,6 +1,6 @@ .. This work is licensed under a Creative Commons Attribution 4.0 International License. .. SPDX-License-Identifier: CC-BY-4.0 -.. Copyright (C) 2024 Nordix Foundation. All rights Reserved +.. Copyright (C) 2024-2025 Nordix Foundation. All rights Reserved .. Copyright (C) 2024 OpenInfra Foundation Europe. All Rights Reserved Query API examples @@ -32,13 +32,14 @@ domain:** :: - GET https:///topology-inventory//schemas?domain=ran + GET https:///topology-inventory//schemas?domain=RAN .. - **Note:** - Partial matches are also supported in the query parameter - using the ’*’ symbol as a wild card. - If the specified domain does - not exist, an empty list is returned. + **Note:** + - The specified domain is case-sensitive. + - If the specified domain does + not exist, an empty list is returned. To get a specific module, supply a module name in the path parameter. For example, /schemas//content @@ -62,7 +63,9 @@ Reading entities and relationships ---------------------------------- To get a list of all entities with all properties in a specified domain -name, use: > /domains/{domainName}/entities +name, use: + +``/domains/{domainName}/entities`` **Example:** Get all entities in the *RAN* domain: @@ -71,7 +74,9 @@ name, use: > /domains/{domainName}/entities GET https:///topology-inventory//domains/RAN/entities To get a list of all available entity types in a specified domain name, -use: > /domains/{domainName}/entity-types +use: + +``/domains/{domainName}/entity-types`` **Example:** Get all entity types in the *RAN* domain: @@ -80,7 +85,9 @@ use: > /domains/{domainName}/entity-types GET https:///topology-inventory//domains/RAN/entity-types To get a list of all available relationship types in a specified domain -name, use: > /domains/{domainName}/relationship-types +name, use: + +``/domains/{domainName}/relationship-types`` **Example:** Get all relationship types in the *RAN* domain: @@ -107,12 +114,17 @@ Moreover, the user only wants those records that have sourceIds containing “SubNetwork=Ireland”. These fields and filters can be defined in the request as follows: - **Parameters:** - **targetFilter:** /NRCellDU - **scopeFilter:** - /sourceIds[contains(@item,'SubNetwork=Ireland')] + **Parameters:** + + - **targetFilter**: ``/NRCellDU`` + - **scopeFilter**: ``/sourceIds[contains(@item,'SubNetwork=Europe')]`` + :: - GET https:///topology-inventory//domains/RAN?targetFilter=/NRCellDU&scopeFilter=/sourceIds[contains(@item,'SubNetwork=Ireland')] + GET https:///topology-inventory//domains/RAN/entities? + targetFilter=/NRCellDU& + scopeFilter=/sourceIds[contains(@item,'SubNetwork=Ireland')] .. @@ -140,17 +152,23 @@ distance in meters from the given point. **Example:** Get all entities with geographical information in the 'EQUIPMENT' domain within 500 meters from a point with latitude and longitude values of 49.40199 and 68.94199 respectively: -``` -GET https:///topology-inventory//domains/EQUIPMENT/entities?scopeFilter=/attributes[withinMeters(@geo-location, 'POINT(49.40199 68.94199)', 500)] -``` +:: + + GET https:///topology-inventory//domains/EQUIPMENT/entities? + scopeFilter=/attributes[withinMeters(@geo-location, 'POINT(49.40199 68.94199)', 500)] + +.. **POLYGON:** This can be used with the *coveredBy* function. It requires the latitude and longitude of the points of the polygon. It returns the desired objects covered by the given polygon. **Example:** Get all 'AntennaModule' entities covered by the polygon with points (48 68) , (50 68), (50 69), (48 69), and (48 68): -``` -GET https:///topology-inventory//domains/EQUIPMENT/entity-types/AntennaModule/entities?scopeFilter=/attributes[coveredBy(@geo-location, 'POLYGON((48 68, 50 68, 50 69, 48 69, 48 68))')] -``` +:: + + GET https:///topology-inventory//domains/EQUIPMENT/entity-types/AntennaModule/entities? + scopeFilter=/attributes[coveredBy(@geo-location, 'POLYGON((48 68, 50 68, 50 69, 48 69, 48 68))')] + +.. **NOTE:** To draw a valid polygon, the first and last points must be identical. diff --git a/docs/supported-filter-options.rst b/docs/supported-filter-options.rst index a7279e4..afce48f 100644 --- a/docs/supported-filter-options.rst +++ b/docs/supported-filter-options.rst @@ -1,6 +1,6 @@ .. This work is licensed under a Creative Commons Attribution 4.0 International License. .. SPDX-License-Identifier: CC-BY-4.0 -.. Copyright (C) 2024 Nordix Foundation. All rights Reserved +.. Copyright (C) 2024-2025 Nordix Foundation. All rights Reserved .. Copyright (C) 2024 OpenInfra Foundation Europe. All Rights Reserved Supported filter options @@ -21,6 +21,103 @@ Sample structure using target and scope filters: See :doc:`Topology & Inventory API ` for all possible filter options and sample responses for each endpoint. +Query grammar +------------- + ++----------------------+---------------------------------+----------------+---------------------------+ +| Grammar element | Syntax | Applies to | Description | ++======================+=================================+================+===========================+ +| Path navigation | | XPath-like structure using / | | targetFilter | | Specifies hierarchical | +| | | for hierarchy navigation | | scopeFilter | | path to attributes, | +| | | | | sourceIds, classifiers, | +| | | | | decorators, or metadata | ++----------------------+---------------------------------+----------------+---------------------------+ +| Attribute | /entity/attributes(attr1,attr2) | targetFilter | | Selects specific | +| selection | | | | attributes for | +| | | | | retrieval | ++----------------------+---------------------------------+----------------+---------------------------+ +| Conditional | [] | scopeFilter | | Encloses filtering | +| brackets | | | | conditions | ++----------------------+---------------------------------+----------------+---------------------------+ +| @ Notation | @attribute | scopeFilter | | Mandatory prefix for | +| | | | | all attribute | +| | | | | references | +| | | | | in conditional brackets | ++----------------------+---------------------------------+----------------+---------------------------+ +| @item | @item | scopeFilter | | item is a Reserved key | +| | | | | word to iterate the | +| | | | | items in the list of | +| | | | | sourceIds or | +| | | | | classifiers | ++----------------------+---------------------------------+----------------+---------------------------+ +| Logical AND | and | scopeFilter | | Combines multiple | +| | | | | conditions within the | +| | | | | same container for | +| | | | | example, it can be used | +| | | | | only within the | +| | | | | conditional brackets | ++----------------------+---------------------------------+----------------+---------------------------+ +| Logical OR | or | scopeFilter | | Specifies alternative | +| | | | | values within the same | +| | | | | container, for example, | +| | | | | it can be used only | +| | | | | within the conditional | +| | | | | brackets | ++----------------------+---------------------------------+----------------+---------------------------+ +| Union (|) | filter1 `|` filter2 | scopeFilter | | Combines results from | +| | | | | multiple filters that | +| | | | | apply to the same or | +| | | | | different containers | ++----------------------+---------------------------------+----------------+---------------------------+ +| Multi-filter (;) | filter1; filter2 | | targetFilter | | Applies multiple | +| | | | scopeFilter | | independent filters in | +| | | | | sequence, each of which | +| | | | | can target a different | +| | | | | container (attributes, | +| | | | | sourceIds, classifiers, | +| | | | | decorators, or | +| | | | | metadata) | ++----------------------+---------------------------------+----------------+---------------------------+ +| contains() | [contains @attribute,'text')] | scopeFilter | | Matches if attribute | +| | | | | contains the specified | +| | | | | substring | +| | | | | (case-sensitive) | ++----------------------+---------------------------------+----------------+---------------------------+ + +Geo-location grammar +-------------------- + ++----------------------+---------------------------------+----------------+---------------------------+ +| Grammar element | Syntax | Applies to | Description | ++======================+=================================+================+===========================+ +| POINT | POINT(lon lat) | scopeFilter | | Specifies geographic | +| | | | | coordinates | +| | | | | (longitude, latitude) | ++----------------------+---------------------------------+----------------+---------------------------+ +| POLYGON | | POLYGON(( | scopeFilter | | Specifies an area as a | +| | | lon1 lat1, lon2 lat2, ..., | | | closed shape defined by | +| | | lonN latN)) | | | multiple | +| | | | | longitude/latitude | +| | | | | pairs | ++----------------------+---------------------------------+----------------+---------------------------+ +| MULTIPOLYGON | | MULTIPOLYGON(( | scopeFilter | | Specifies a set of | +| | | (lon1 lat1, lon2 lat2, ..., | | | polygons | +| | | lonN latN)), ((lon1 lat1, | | | | +| | | lon2 lat2, ..., lonN latN))) | | | | ++----------------------+---------------------------------+----------------+---------------------------+ +| withinMeters() | | withinMeters(@geo-location, | scopeFilter | | Filters entities within | +| | | POINT(lon lat), distance in | | | a specified distance | +| | | meters) | | | (in meters) of a | +| | | | | geographic point | +| | | | | +| | | | | ++----------------------+---------------------------------+----------------+---------------------------+ +| coveredBy() | | coveredBy(@geo-location, | scopeFilter | | Filters entities whose | +| | | 'POLYGON((...))') | | | geo-location is inside | +| | | | | the specified polygon | +| | | | | or multipolygon area | ++----------------------+---------------------------------+----------------+---------------------------+ + Querying simple entities ------------------------ @@ -132,9 +229,16 @@ The *entityTypeName* is used as the root of the queries. +------------------------------------------+-------------+----------------+--------------+----------------------------+--------------------------------------------------+ | | To return the ids for all instances of | RAN | NRCellDU | | /serving-antennaModule/ | | All NRCellDU entities served by AntennaModule | | | an entityTypeName related by an | | | | attributes[withinMeters | | entities within 500.5 meters from a point with | -| | association to other entities whose | | | | (@geo-location, 'POINT( | | latitude and longitude values of -73.958444 | -| | attribute matches the given | | | | -73.958444 40.800533)', | | and 40.800533 respectively. | +| | association to other entities whose | | | | (@geo-location, 'POINT( | | latitude and longitude values of 40.800533 | +| | attribute matches the given | | | | 40.800533 -73.958444)', | | and -73.958444 respectively. | | | *scopeFilter* parameter. | | | | 500.5)] | | ++------------------------------------------+-------------+----------------+--------------+----------------------------+--------------------------------------------------+ +| | To return the ids for all instances of | RAN | NRCellDU | | /serving-antennaModule/ | | All NRCellDU entities served by AntennaModule | +| | an entityTypeName related by an | | | | /classifiers[@item= | | whose classifiers match test-app-module:Rural. | +| | association to other entities whose | | | | 'test-app-module:Rural'] | | +| | classifiers/decorators/sourceId | | | | | | +| | matches the given *scopeFilter* | | | | | | +| | parameter | | | | | | +------------------------------------------+-------------+----------------+--------------+----------------------------+--------------------------------------------------+ **/domains/{domainName}/entities** @@ -165,6 +269,12 @@ The *entityTypeName* is used as the root of the queries. | | attributes match a specified | | | | | | | *scopeFilter* query. | | | | | +------------------------------------------+-------------+----------------+-------------------------------------------+--------------------------------------------------+ +| | To return the ids of all entities in a | EQUIPMENT | | /grouped-by-sector/classifiers[ | | All entities that are grouped by a Sector | +| | given domain related by one or | | | @item='test-app-module:Rural'] | | whose classifiers match test-app-module:Rural. | +| | more associations to other entities | | | | | +| | whose classifiers/decorators/sourceId | | | | | +| | match a specified scopeFilter query. | | | | | ++------------------------------------------+-------------+----------------+-------------------------------------------+--------------------------------------------------+ Querying entities for relationships ----------------------------------- @@ -179,19 +289,19 @@ The *entityTypeName* is used as the root of the queries. | | | | | | | | | | | | | | | | +==========================================+=============+================+===================+=================+============================+=====================================================+ -| | To return the relationships for a | RAN | ODUFunction | urn\:3gpp:dn: | | | | All relations for the ODUFunction with id | -| | given entity specified by its id. | | | ManagedElement=1, | | | | *urn\:3gpp:dn: ManagedElement=1, ODUFunction=1* | +| | To return the relationships for a | RAN | ODUFunction | `urn:3gpp:dn:` | | | | All relations for the ODUFunction with id | +| | given entity specified by its id. | | | ManagedElement=1, | | | | *urn:3gpp:dn:ManagedElement=1,ODUFunction=1* | | | | | ODUFunction=1 | | | | +------------------------------------------+-------------+----------------+-------------------+-----------------+----------------------------+-----------------------------------------------------+ -| | To return specific relationships for a | REL_OAM_RAN | ODUFunction | urn\:3gpp:dn: | /MANAGEDELEMENT | | | All *MANAGEDELEMENT _MANAGES _ODUFUNCTION* | +| | To return specific relationships for a | REL_OAM_RAN | ODUFunction | `urn:3gpp:dn:` | /MANAGEDELEMENT | | | All *MANAGEDELEMENT _MANAGES _ODUFUNCTION* | | | given entity specified by its id. | | | ManagedElement=1, | _MANAGES | | | relations for the ODUFunction with id | -| | | | ODUFunction=1 | _ODUFUNCTION | | | *urn\:3gpp:dn: ManagedElement=1, ODUFunction=1* | +| | | | ODUFunction=1 | _ODUFUNCTION | | | *urn:3gpp:dn:ManagedElement=1,ODUFunction=1* | +------------------------------------------+-------------+----------------+-------------------+-----------------+----------------------------+-----------------------------------------------------+ -| | To return specific relationships for | REL_OAM_RAN | ODUFunction | urn\:3gpp:dn: | | /managed-by-managedElement | | All *MANAGEDELEMENT _MANAGES _ODUFUNCTION* | -| | an entity specified by its id to | | | ManagedElement=1, | | [@id = 'urn\:3gpp:dn: | | relations for the ODUFunction with id | -| | another entity using its id and | | | ODUFunction=1 | | ManagedElement=1'] | | *urn\:3gpp:dn: ManagedElement=1, ODUFunction=1* | +| | To return specific relationships for | REL_OAM_RAN | ODUFunction | `urn:3gpp:dn:` | | /managed-by-managedElement | | All *MANAGEDELEMENT_MANAGES_ODUFUNCTION* | +| | an entity specified by its id to | | | ManagedElement=1, | | [@id = '`urn:3gpp:dn:` | | relations for the ODUFunction with id | +| | another entity using its id and | | | ODUFunction=1 | | ManagedElement=1'] | | *urn:3gpp:dn:ManagedElement=1,ODUFunction=1* | | | association. | | | | | | | where the managed element is | -| | | | | | | | *urn\:3gpp:dn: ManagedElement=1*. | +| | | | | | | | *urn:3gpp:dn:ManagedElement=1*. | +------------------------------------------+-------------+----------------+-------------------+-----------------+----------------------------+-----------------------------------------------------+ Querying on relationships @@ -395,47 +505,65 @@ This functionality is supported by the following endpoints **/domains/{domainName}/relationship-types/{relationshipTypeName}/relationships** -+-------------------------------+--------+-------------------------+--------------------+-----------------------------+ -| Use case | entity | relationshipTypeName | targetFilter | scopeFilter | -| | | | | | -| | Name | | | | -+===============================+========+=========================+====================+=============================+ -| | Return all related | | MANAGEDELEMENT _MANAGES | /classifiers | | -| | relationship IDs and | | _ORUFUNCTION | | | -| | classifiers. | | | | | -+-------------------------------+--------+-------------------------+--------------------+-----------------------------+ -| | Return all related | | MANAGEDELEMENT _MANAGES | /decorators | | -| | relationship IDs and | | _ORUFUNCTION | | | -| | decorators. | | | | | -+-------------------------------+--------+-------------------------+--------------------+-----------------------------+ -| | Return related relationship | | MANAGEDELEMENT _MANAGES | | /classifiers[@item = | -| | IDs that match the | | _ORUFUNCTION | | 'odu-function-model | -| | classifier and decorator. | | | | :Indoor']; | -| | | | | | -| | | | | /decorators[@odu-function | -| | | | | -model:textdata = | -| | | | | 'Stockholm'] | -+-------------------------------+--------+-------------------------+--------------------+-----------------------------+ -| | Return related relationship | | MANAGEDELEMENT _MANAGES | /classifiers | /classifiers[contains | -| | IDs and classifiers that | | _ORUFUNCTION | | (@item, 'Ind')] | -| | are partially matched | | | | | -| | for the classifier. | | | | | -+-------------------------------+--------+-------------------------+--------------------+-----------------------------+ -| | Return related relationship | | MANAGEDELEMENT _MANAGES | /decorators | /decorators[contains | -| | IDs and decorators where | | _ORUFUNCTION | | (@odu-function-model: | -| | the key matches exactly and | | | | textdata, 'Stock')] | -| | the value matches | | | | | -| | partially. | | | | | -+-------------------------------+--------+-------------------------+--------------------+-----------------------------+ -| | Return related relationship | | MANAGEDELEMENT _MANAGES | | /classifiers | /classifiers[contains | -| | IDs, decorators, and | | _ORUFUNCTION | | /decorators | (@item, 'Ind')]; | -| | classifiers where decorator | | | | /decorators[contains | -| | key is exact and value | | | | (@odu-function-model: | -| | partially matches, and | | | | textdata, 'Stock')] | -| | classifiers partially match | | | | | -| | the parameters. | | | | | -+-------------------------------+--------+-------------------------+--------------------+-----------------------------+ ++-------------------------------+-------------------------+--------------------+-----------------------------+-----------------------------+ +| Use case | relationshipTypeName | targetFilter | scopeFilter | Query result | +| | | | | | +| | | | | | ++===============================+=========================+====================+=============================+=============================+ +| | Return all related | | MANAGEDELEMENT | /classifiers | | | All MANAGEDELEMENT | +| | relationship IDs and | | _MANAGES | | | | _MANAGES_ORUFUNCTION IDs | +| | classifiers. | | _ORUFUNCTION | | | | and classifiers. | ++-------------------------------+-------------------------+--------------------+-----------------------------+-----------------------------+ +| | Return all related | | MANAGEDELEMENT | /decorators | | | All MANAGEDELEMENT | +| | relationship IDs and | | _MANAGES | | | | _MANAGES_ORUFUNCTION IDs | +| | decorators. | | _ORUFUNCTION | | | | and decorators. | ++-------------------------------+-------------------------+--------------------+-----------------------------+-----------------------------+ +| | Return related relationship | | MANAGEDELEMENT | | /classifiers[@item = | | All MANAGEDELEMENT | +| | IDs that match the | | _MANAGES | | 'odu-function-model | | _MANAGES_ORUFUNCTION IDs | +| | classifier and decorator. | | _ORUFUNCTION | | :Indoor']; | | and decorators where key | +| | | | | | of the decorator is | +| | | | /decorators[@odu-function | | "odu-function-model | +| | | | -model:textdata = | | :textdata" and the value | +| | | | 'Stockholm'] | | of the decorator is | +| | | | | | 'Stockholm' and | +| | | | | | classifiers exactly | +| | | | | | contains "odu-function | +| | | | | | -model:Indoor". | ++-------------------------------+-------------------------+--------------------+-----------------------------+-----------------------------+ +| | Return related relationship | | MANAGEDELEMENT | /classifiers | /classifiers[contains | | All MANAGEDELEMENT | +| | IDs and classifiers that | | _MANAGES | | (@item, 'Ind')] | | _MANAGES_ORUFUNCTION IDs | +| | are partially matched | | _ORUFUNCTION | | | | and classifiers where | +| | for the classifier. | | | | | classifiers partially | +| | | | | | contains the text "Ind". | ++-------------------------------+-------------------------+--------------------+-----------------------------+-----------------------------+ +| | Return related relationship | | MANAGEDELEMENT | /decorators | /decorators[contains | | All MANAGEDELEMENT | +| | IDs and decorators where | | _MANAGES | | (@odu-function-model: | | _MANAGES_ORUFUNCTION IDs | +| | the key matches exactly and | | _ORUFUNCTION | | textdata, 'Stock')] | | and decorators where | +| | the value matches | | | | | where key of the | +| | partially. | | | | | decorator is "odu- | +| | | | | | function-model:textdata" | +| | | | | | and the value of the | +| | | | | | decorator partially | +| | | | | | contains 'Stock'. | ++-------------------------------+-------------------------+--------------------+-----------------------------+-----------------------------+ +| | Return related relationship | | MANAGEDELEMENT | | /classifiers | /classifiers[contains | | All MANAGEDELEMENT | +| | IDs, decorators, and | | _MANAGES | | /decorators | (@item, 'Ind')]; | | _MANAGES_ORUFUNCTION IDs, | +| | classifiers where decorator | | _ORUFUNCTION | | /decorators[contains | | decorators and | +| | key is exact and value | | | (@odu-function-model: | | classifiers where where | +| | partially matches, and | | | textdata, 'Stock')] | | the key of the decorator | +| | classifiers partially match | | | | | is "odu-function-model | +| | the parameters. | | | | | :textdata", the value of | +| | | | | | the decorator partially | +| | | | | | contains 'Stock', and the | +| | | | | | classifiers partially | +| | | | | | contain the text "Ind". | ++-------------------------------+-------------------------+--------------------+-----------------------------+-----------------------------+ + +**Example:** Get the relationships that have the classifier odu-function-model:Indoor: +:: + + GET https:///topology-inventory//domains/REL_OAM_RAN/relationship-types/MANAGEDELEMENT_MANAGES_ODUFUNCTION/relationships?targetFilter=/classifiers&scopeFilter=/classifiers[@item = 'odu-function-model:Indoor'] **Result** @@ -491,22 +619,28 @@ For supported geometry objects, see `Querying on geographical information <#capa | Use case | entityName | targetFilter | scopeFilter | Query result | +------------------------------------------+---------------+----------------+-------------------------------------------+--------------------------------------------------+ | | Return the ids for all instances of an | AntennaModule | | /attributes[coveredBy(@geo-location, | | All AntennaModule entities covered by the | -| | entityTypeName covered by the given | | | 'POLYGON ((-73.958444 40.800533 | | polygon ((-73.958444 40.800533, -73.981962 | -| | polygon | | | ,-73.981962 40.768558, -73.973207 | | 40.768558, -73.973207 40.765048, -73.949861 | -| | | | 40.765048, -73.949861 40.797024 | | 40.797024, -73.958444 40.800533)). | -| | | | ,-73.958444 40.800533))')] | | | +| | entityTypeName covered by the given | | | 'POLYGON ((40.800533 -73.958444 | | polygon ((40.800533 -73.958444, 40.768558 | +| | polygon | | | ,40.768558 -73.981962, 40.765048 | | -73.981962, 40.765048 -73.973207, 40.797024 | +| | | | -73.973207, 40.797024 -73.949861 | | -73.949861, 40.800533 -73.958444)). | +| | | | ,40.800533 -73.958444))')] | | | +------------------------------------------+---------------+----------------+-------------------------------------------+--------------------------------------------------+ | | Return the attributes for all | AntennaModule | /attributes | /attributes[coveredBy(@geo-location, | | All AntennaModule entities with attributes | -| | instances of an entityTypeName covered | | | 'POLYGON ((40 40, 20 45, 45 30, | | covered by the polygon | -| | by the given polygon. | | | 40 40))')] | | ((40 40, 20 45, 45 30, 40 40)). | +| | instances of an entityTypeName covered | | | 'POLYGON ((40 40, 45 20, 30 45, 40 40 | | covered by the polygon | +| | by the given polygon. | | | ))')] | | ((40 40, 45 20, 30 45, 40 40)). | +------------------------------------------+---------------+----------------+-------------------------------------------+--------------------------------------------------+ | | Return the ids for all instances of an | AntennaModule | | /attributes[withinMeters(@geo-location, | | All AntennaModule entities within 500.5 meters | -| | entityTypeName within a specified | | | 'POINT(-73.958444 40.800533)', 500.5)] | | from a point with latitude and longitude | -| | distance in meters from a point. | | | | | values of -73.958444 and 40.800533 | +| | entityTypeName within a specified | | | 'POINT(40.800533 -73.958444)', 500.5)] | | from a point with latitude and longitude | +| | distance in meters from a point. | | | | | values of 40.800533 and -73.958444 | | | | | | | respectively. | +------------------------------------------+---------------+----------------+-------------------------------------------+--------------------------------------------------+ +| | Return the ids for all instances of an | AntennaModule | | /attributes[coveredBy(@geo-location, | | All AntennaModule entities covered by the | +| | entityTypeName covered by the given | | | 'MULTIPOLYGON (((40 40, 20 45, 45 30, 40 | | given collection of polygons (((40 40, 20 45, | +| | collection of polygons. | | | 40)),((20 35, 10 30, 10 10, 30 5, 45 20, | | 45 30, 40 40)),((20 35, 10 30, 10 10, 30 5, 45 | +| | | | 20 35)),((30 20, 20 15, 20 25, 30 | | 20, 20 35)),((30 20, 20 15, 20 25, 30 20))). | +| | | | 20)))')] | | ++------------------------------------------+---------------+----------------+-------------------------------------------+--------------------------------------------------+ -**Example:** Get all 'AntennaModule' entities covered by the polygon with points (48 68), (50 68), (50 69), (48 69), and (48 68): +**Example:** Get all 'AntennaModule' entities covered by the polygon with points (68 48) , (68 50), (69 50), (69 48), and (68 48): :: @@ -527,19 +661,19 @@ For supported geometry objects, see `Querying on geographical information <#capa } ], "self": { - "href": "/domains/EQUIPMENT/entity-types/AntennaModule/entities?offset=0&limit=500&scopeFilter=/attributes[coveredBy(@geo-location, 'POLYGON((48 68, 50 68, 50 69, 48 69, 48 68))')]" + "href": "/domains/EQUIPMENT/entity-types/AntennaModule/entities?offset=0&limit=500&scopeFilter=/attributes[coveredBy(@geo-location, 'POLYGON((68 48, 68 50, 69 50, 69 48, 68 48))')]" }, "first": { - "href": "/domains/EQUIPMENT/entity-types/AntennaModule/entities?offset=0&limit=500&scopeFilter=/attributes[coveredBy(@geo-location, 'POLYGON((48 68, 50 68, 50 69, 48 69, 48 68))')]" + "href": "/domains/EQUIPMENT/entity-types/AntennaModule/entities?offset=0&limit=500&scopeFilter=/attributes[coveredBy(@geo-location, 'POLYGON((68 48, 68 50, 69 50, 69 48, 68 48))')]" }, "prev": { - "href": "/domains/EQUIPMENT/entity-types/AntennaModule/entities?offset=0&limit=500&scopeFilter=/attributes[coveredBy(@geo-location, 'POLYGON((48 68, 50 68, 50 69, 48 69, 48 68))')]" + "href": "/domains/EQUIPMENT/entity-types/AntennaModule/entities?offset=0&limit=500&scopeFilter=/attributes[coveredBy(@geo-location, 'POLYGON((68 48, 68 50, 69 50, 69 48, 68 48))')]" }, "next": { - "href": "/domains/EQUIPMENT/entity-types/AntennaModule/entities?offset=0&limit=500&scopeFilter=/attributes[coveredBy(@geo-location, 'POLYGON((48 68, 50 68, 50 69, 48 69, 48 68))')]" + "href": "/domains/EQUIPMENT/entity-types/AntennaModule/entities?offset=0&limit=500&scopeFilter=/attributes[coveredBy(@geo-location, 'POLYGON((68 48, 68 50, 69 50, 69 48, 68 48))')]" }, "last": { - "href": "/domains/EQUIPMENT/entity-types/AntennaModule/entities?offset=0&limit=500&scopeFilter=/attributes[coveredBy(@geo-location, 'POLYGON((48 68, 50 68, 50 69, 48 69, 48 68))')]" + "href": "/domains/EQUIPMENT/entity-types/AntennaModule/entities?offset=0&limit=500&scopeFilter=/attributes[coveredBy(@geo-location, 'POLYGON((68 48, 68 50, 69 50, 69 48, 68 48))')]" }, "totalCount": 1 } @@ -550,26 +684,32 @@ For supported geometry objects, see `Querying on geographical information <#capa | Use case | targetFilter | scopeFilter | Query result | +------------------------------------------+----------------+-------------------------------------------+--------------------------------------------------+ | | Return the ids for all entities in a | | /attributes[coveredBy(@geo-location, | | All AntennaModule entities covered by the | -| | given domain that is covered by a | | 'POLYGON ((-73.958444 40.800533 | | polygon ((-73.958444 40.800533, -73.981962 | -| | specified polygon. | | ,-73.981962 40.768558, -73.973207 | | 40.768558, -73.973207 40.765048, -73.949861 | -| | | 40.765048, -73.949861 40.797024 | | 40.797024, -73.958444 40.800533)). | -| | | ,-73.958444 40.800533))')] | | | +| | given domain that is covered by a | | 'POLYGON ((40.800533 -73.958444 | | polygon ((40.800533 -73.958444, 40.768558 | +| | specified polygon. | | ,40.768558 -73.981962, 40.765048 | | -73.981962, 40.765048 -73.973207, 40.797024 | +| | | -73.973207, 40.797024 -73.949861 | | -73.949861, 40.800533 -73.958444)). | +| | | ,40.800533 -73.958444))')] | | +------------------------------------------+----------------+-------------------------------------------+--------------------------------------------------+ | | Return the attributes for all | /AntennaModule | /attributes[coveredBy(@geo-location, | | All AntennaModule entities covered by | -| | AntennaModule entities in the given | /attributes | 'POLYGON ((40 40, 20 45, 45 30, | | the polygon ((20 35, 10 30, 10 10, 30 | -| | domain covered by a specified polygon. | | 40 40))')] | | 5, 45 20, 20 35)). | +| | AntennaModule entities in the given | /attributes | 'POLYGON ((40 40, 45 20, 30 45, 40 40)) | | the polygon ((40 40, 45 20, 30 45, 40 40)). | +| | domain covered by a specified polygon. | | ')] | | +------------------------------------------+----------------+-------------------------------------------+--------------------------------------------------+ | | Return the ids for all AntennaModule | /AntennaModule | /attributes[withinMeters(@geo-location, | | All AntennaModule entities within 500.5 meters | -| | entities in the given domain within a | | 'POINT(-73.958444 40.800533)', 500.5)] | | from a point with latitude and longitude | -| | specified distance in meters from a | | | | values of -73.958444 and 40.800533 | +| | entities in the given domain within a | | 'POINT(40.800533 -73.958444)', 500.5)] | | from a point with latitude and longitude | +| | specified distance in meters from a | | | | values of 40.800533 and -73.958444 | | | point. | | | | respectively. | +------------------------------------------+----------------+-------------------------------------------+--------------------------------------------------+ +| | Return the ids for all entities in a | | /attributes[coveredBy(@geo-location, | | All entities covered by the given collection | +| | given domain that is covered by a | | 'MULTIPOLYGON (((40 40, 20 45, 45 30, 40 | | of polygons (((40 40, 20 45, 45 30, 40 40)),(( | +| | specified polygon. | | 40)),((20 35, 10 30, 10 10, 30 5, 45 20, | | 20 35, 10 30, 10 10, 30 5, 45 20, 20 35)),(( | +| | | 20 35)),((30 20, 20 15, 20 25, 30 20))) | | 30 20, 20 15, 20 25, 30 20))). | +| | | ')] | | ++------------------------------------------+----------------+-------------------------------------------+--------------------------------------------------+ -**Example:** Get all entities in the 'EQUIPMENT' domain within 500 meters from a point with latitude and longitude values of 49.40199 and 68.94199 respectively: +**Example:** Get all entities in the 'EQUIPMENT' domain within 500 meters from a point with latitude and longitude values of 68.94199 and 49.40199 respectively: :: - GET https:///topology-inventory//domains/EQUIPMENT/entities?scopeFilter=/attributes[withinMeters(@geo-location, 'POINT(49.40199 68.94199)', 500)] + GET https:///topology-inventory//domains/EQUIPMENT/entities?scopeFilter=/attributes[withinMeters(@geo-location, 'POINT(68.94199 49.40199)', 500)] **Result** @@ -586,16 +726,16 @@ For supported geometry objects, see `Querying on geographical information <#capa } ], "self": { - "href": "/domains/EQUIPMENT/entities?offset=0&limit=500&scopeFilter=/attributes[withinMeters(@geo-location, 'POINT(49.40199 68.94199)', 500)]" + "href": "/domains/EQUIPMENT/entities?offset=0&limit=500&scopeFilter=/attributes[withinMeters(@geo-location, 'POINT(68.94199 49.40199)', 500)]" }, "first": { - "href": "/domains/EQUIPMENT/entities?offset=0&limit=500&scopeFilter=/attributes[withinMeters(@geo-location, 'POINT(49.40199 68.94199)', 500)]" + "href": "/domains/EQUIPMENT/entities?offset=0&limit=500&scopeFilter=/attributes[withinMeters(@geo-location, 'POINT(68.94199 49.40199)', 500)]" }, "prev": { - "href": "/domains/EQUIPMENT/entities?offset=0&limit=500&scopeFilter=/attributes[withinMeters(@geo-location, 'POINT(49.40199 68.94199)', 500)]" + "href": "/domains/EQUIPMENT/entities?offset=0&limit=500&scopeFilter=/attributes[withinMeters(@geo-location, 'POINT(68.94199 49.40199)', 500)]" }, "next": { - "href": "/domains/EQUIPMENT/entities?offset=0&limit=500&scopeFilter=/attributes[withinMeters(@geo-location, 'POINT(49.40199 68.94199)', 500)]" + "href": "/domains/EQUIPMENT/entities?offset=0&limit=500&scopeFilter=/attributes[withinMeters(@geo-location, 'POINT(68.94199 49.40199)', 500)]" }, "totalCount": 1 } -- 2.16.6