From bdd72988bb157b7e611569e24b821867ce1d8787 Mon Sep 17 00:00:00 2001 From: JvD_Ericsson Date: Fri, 6 Dec 2024 15:14:02 +0000 Subject: [PATCH] TEIV: update docs to align with geo-location and groupings changes Change-Id: I6df245cb7f1864bb557b656ba0998845f8fecc5e Signed-off-by: JvD_Ericsson --- docs/_static/data-model/o-ran-smo-teiv-cloud.svg | 168 ++++---- .../data-model/o-ran-smo-teiv-equipment.svg | 126 +++--- docs/_static/data-model/o-ran-smo-teiv-oam.svg | 36 +- docs/_static/data-model/o-ran-smo-teiv-ran.svg | 446 +++++++++------------ .../o-ran-smo-teiv-rel-equipment-ran-rel.svg | 55 ++- docs/_static/data-model/overall-rel.svg | 361 +++++++++-------- docs/_static/dataCloudEvent.svg | 26 +- docs/developer-guide.rst | 50 +++ ...discover-and-reconciliation-interface-guide.rst | 241 ++++++----- docs/discover-and-reconciliation-interface.rst | 446 +++++++++++---------- docs/groupings.rst | 355 ++++++++++++++++ docs/index.rst | 1 + docs/query-api-examples.rst | 35 ++ docs/supported-filter-options.rst | 183 ++++++++- 14 files changed, 1591 insertions(+), 938 deletions(-) create mode 100644 docs/groupings.rst diff --git a/docs/_static/data-model/o-ran-smo-teiv-cloud.svg b/docs/_static/data-model/o-ran-smo-teiv-cloud.svg index faf73cf..d31da8a 100644 --- a/docs/_static/data-model/o-ran-smo-teiv-cloud.svg +++ b/docs/_static/data-model/o-ran-smo-teiv-cloud.svg @@ -1,177 +1,165 @@ - - + + o-ran-smo-teiv-cloud - + o-ran-smo-teiv-cloud - -o-ran-smo-teiv-cloud + +o-ran-smo-teiv-cloud CloudifiedNF - -CloudifiedNF + +CloudifiedNF o-ran-smo-teiv-cloud->CloudifiedNF - - + + NFDeployment - -NFDeployment + +NFDeployment o-ran-smo-teiv-cloud->NFDeployment - - + + NodeCluster - -NodeCluster + +NodeCluster o-ran-smo-teiv-cloud->NodeCluster - - + + OCloudNamespace - -OCloudNamespace + +OCloudNamespace o-ran-smo-teiv-cloud->OCloudNamespace - - + + OCloudSite - -OCloudSite + +OCloudSite o-ran-smo-teiv-cloud->OCloudSite - - + + CloudifiedNF-attributes - - -id - -string - -name - -string - + +id +string +sourceIds +<< Refer to Module >> + attributes: +        name +string NFDeployment-attributes - - -id - -string - -name - -string - + +id +string +sourceIds +<< Refer to Module >> + attributes: +        name +string NodeCluster-attributes - - -id - -string - -name - -string - + +id +string +sourceIds +<< Refer to Module >> + attributes: +        name +string OCloudNamespace-attributes - - -id - -string - -name - -string - + +id +string +sourceIds +<< Refer to Module >> + attributes: +        name +string OCloudSite-attributes - - -geo-location - -<< Refer to Module >> - -id - -string - -name - -string - + +id +string +sourceIds +<< Refer to Module >> + attributes: +        geo-location +<< Refer to Module >> +        name +string CloudifiedNF->CloudifiedNF-attributes - - + + NFDeployment->NFDeployment-attributes - - + + NodeCluster->NodeCluster-attributes - - + + OCloudNamespace->OCloudNamespace-attributes - - + + OCloudSite->OCloudSite-attributes - - + + diff --git a/docs/_static/data-model/o-ran-smo-teiv-equipment.svg b/docs/_static/data-model/o-ran-smo-teiv-equipment.svg index 2d1f842..39b7f43 100644 --- a/docs/_static/data-model/o-ran-smo-teiv-equipment.svg +++ b/docs/_static/data-model/o-ran-smo-teiv-equipment.svg @@ -1,109 +1,95 @@ - - + + o-ran-smo-teiv-equipment - + o-ran-smo-teiv-equipment - -o-ran-smo-teiv-equipment + +o-ran-smo-teiv-equipment AntennaModule - -AntennaModule + +AntennaModule o-ran-smo-teiv-equipment->AntennaModule - - + + Site - -Site + +Site o-ran-smo-teiv-equipment->Site - - + + AntennaModule-attributes - - -antennaBeamWidth - -uint32 - -antennaModelNumber - -string - -electricalAntennaTilt - -int32 - -geo-location - -<< Refer to Module >> - -id - -string - -mechanicalAntennaBearing - -int32 - -mechanicalAntennaTilt - -int32 - -positionWithinSector - -string - -totalTilt - -int32 - + +id +string +sourceIds +<< Refer to Module >> + attributes: +        antennaBeamWidth +uint32 +        antennaModelNumber +string +        azimuth +decimal64 +        electricalAntennaTilt +int32 +        geo-location +<< Refer to Module >> +        horizontalBeamWidth +decimal64 +        mechanicalAntennaBearing +int32 +        mechanicalAntennaTilt +int32 +        positionWithinSector +string +        totalTilt +int32 +        verticalBeamWidth +decimal64 Site-attributes - - -geo-location - -<< Refer to Module >> - -id - -string - -name - -string - + +id +string +sourceIds +<< Refer to Module >> + attributes: +        geo-location +<< Refer to Module >> +        name +string AntennaModule->AntennaModule-attributes - - + + Site->Site-attributes - - + + diff --git a/docs/_static/data-model/o-ran-smo-teiv-oam.svg b/docs/_static/data-model/o-ran-smo-teiv-oam.svg index d08304e..17fb22d 100644 --- a/docs/_static/data-model/o-ran-smo-teiv-oam.svg +++ b/docs/_static/data-model/o-ran-smo-teiv-oam.svg @@ -1,41 +1,41 @@ - - + + o-ran-smo-teiv-oam - + o-ran-smo-teiv-oam - -o-ran-smo-teiv-oam + +o-ran-smo-teiv-oam ManagedElement - -ManagedElement + +ManagedElement o-ran-smo-teiv-oam->ManagedElement - - + + ManagedElement-attributes - - -id - -string - + +id +string +sourceIds +<< Refer to Module >> + attributes: ManagedElement->ManagedElement-attributes - - + + diff --git a/docs/_static/data-model/o-ran-smo-teiv-ran.svg b/docs/_static/data-model/o-ran-smo-teiv-ran.svg index d761431..a00a178 100644 --- a/docs/_static/data-model/o-ran-smo-teiv-ran.svg +++ b/docs/_static/data-model/o-ran-smo-teiv-ran.svg @@ -1,421 +1,359 @@ - - + + o-ran-smo-teiv-ran - + o-ran-smo-teiv-ran - -o-ran-smo-teiv-ran + +o-ran-smo-teiv-ran AntennaCapability - -AntennaCapability + +AntennaCapability o-ran-smo-teiv-ran->AntennaCapability - - + + NRCellCU - -NRCellCU + +NRCellCU o-ran-smo-teiv-ran->NRCellCU - - + + NRCellDU - -NRCellDU + +NRCellDU o-ran-smo-teiv-ran->NRCellDU - - + + NRSectorCarrier - -NRSectorCarrier + +NRSectorCarrier o-ran-smo-teiv-ran->NRSectorCarrier - - + + NearRTRICFunction - -NearRTRICFunction + +NearRTRICFunction o-ran-smo-teiv-ran->NearRTRICFunction - - + + OCUCPFunction - -OCUCPFunction + +OCUCPFunction o-ran-smo-teiv-ran->OCUCPFunction - - + + OCUUPFunction - -OCUUPFunction + +OCUUPFunction o-ran-smo-teiv-ran->OCUUPFunction - - + + ODUFunction - -ODUFunction + +ODUFunction o-ran-smo-teiv-ran->ODUFunction - - + + ORUFunction - -ORUFunction + +ORUFunction o-ran-smo-teiv-ran->ORUFunction - - + + Sector - -Sector + +Sector o-ran-smo-teiv-ran->Sector - - + + AntennaCapability-attributes - - -eUtranFqBands - -string - -geranFqBands - -string - -id - -string - -nRFqBands - -string - + +id +string +sourceIds +<< Refer to Module >> + attributes: +        eUtranFqBands +string +        geranFqBands +string +        nRFqBands +string NRCellCU-attributes - - -cellLocalId - -int32 - -id - -string - -nCI - -int64 - -nRTAC - -int32 - -plmnId - -<< Refer to Module >> - + +id +string +sourceIds +<< Refer to Module >> + attributes: +        cellLocalId +int32 +        nCI +int64 +        nRTAC +int32 +        plmnId +<< Refer to Module >> NRCellDU-attributes - - -cellLocalId - -int32 - -id - -string - -nCI - -int64 - -nRPCI - -int32 - -nRTAC - -int32 - + +id +string +sourceIds +<< Refer to Module >> + attributes: +        cellLocalId +int32 +        nCI +int64 +        nRPCI +int32 +        nRTAC +int32 NRSectorCarrier-attributes - - -arfcnDL - -int32 - -arfcnUL - -int32 - -bSChannelBwDL - -int32 - -frequencyDL - -int32 - -frequencyUL - -int32 - -id - -string - + +id +string +sourceIds +<< Refer to Module >> + attributes: +        arfcnDL +int32 +        arfcnUL +int32 +        bSChannelBwDL +int32 +        frequencyDL +int32 +        frequencyUL +int32 NearRTRICFunction-attributes - - -id - -string - -nearRtRicId - -int64 - -pLMNId - -<< Refer to Module >> - + +id +string +sourceIds +<< Refer to Module >> + attributes: +        nearRtRicId +int64 +        pLMNId +<< Refer to Module >> OCUCPFunction-attributes - - -gNBCUName - -string - -gNBId - -int64 - -gNBIdLength - -int32 - -id - -string - -pLMNId - -<< Refer to Module >> - + +id +string +sourceIds +<< Refer to Module >> + attributes: +        gNBCUName +string +        gNBId +int64 +        gNBIdLength +int32 +        pLMNId +<< Refer to Module >> OCUUPFunction-attributes - - -gNBId - -int64 - -gNBIdLength - -int32 - -id - -string - -pLMNIdList - -[] - + +id +string +sourceIds +<< Refer to Module >> + attributes: +        gNBId +int64 +        gNBIdLength +int32 +        pLMNIdList +[] ODUFunction-attributes - - -gNBDUId - -int64 - -gNBId - -int64 - -gNBIdLength - -int32 - -id - -string - + +id +string +sourceIds +<< Refer to Module >> + attributes: +        dUpLMNId +<< Refer to Module >> +        gNBDUId +int64 +        gNBId +int64 +        gNBIdLength +int32 ORUFunction-attributes - - -id - -string - -oruId - -int64 - + +id +string +sourceIds +<< Refer to Module >> + attributes: +        oruId +int64 Sector-attributes - - -azimuth - -decimal64 - -geo-location - -<< Refer to Module >> - -id - -string - -sectorId - -uint64 - + +id +string +sourceIds +<< Refer to Module >> + attributes: +        azimuth +decimal64 +        geo-location +<< Refer to Module >> +        sectorId +uint64 AntennaCapability->AntennaCapability-attributes - - + + NRCellCU->NRCellCU-attributes - - + + NRCellDU->NRCellDU-attributes - - + + NRSectorCarrier->NRSectorCarrier-attributes - - + + NearRTRICFunction->NearRTRICFunction-attributes - - + + OCUCPFunction->OCUCPFunction-attributes - - + + OCUUPFunction->OCUUPFunction-attributes - - + + ODUFunction->ODUFunction-attributes - - + + ORUFunction->ORUFunction-attributes - - + + Sector->Sector-attributes - - + + diff --git a/docs/_static/data-model/o-ran-smo-teiv-rel-equipment-ran-rel.svg b/docs/_static/data-model/o-ran-smo-teiv-rel-equipment-ran-rel.svg index c17bc1c..6c28dff 100644 --- a/docs/_static/data-model/o-ran-smo-teiv-rel-equipment-ran-rel.svg +++ b/docs/_static/data-model/o-ran-smo-teiv-rel-equipment-ran-rel.svg @@ -1,13 +1,13 @@ - + moduleName - + AntennaModule - -AntennaModule + +AntennaModule @@ -16,28 +16,43 @@ AntennaCapability - + AntennaModule->AntennaCapability - - -SERVES -0..* -0..* + + +SERVES +0..* +0..* - + +NRCellDU + +NRCellDU + + + +AntennaModule->NRCellDU + + +SERVES +1..* +0..* + + + Sector - -Sector + +Sector - + Sector->AntennaModule - - -GROUPS -0..1 -0..* + + +GROUPS +0..1 +0..* diff --git a/docs/_static/data-model/overall-rel.svg b/docs/_static/data-model/overall-rel.svg index dd9130e..f212c5b 100644 --- a/docs/_static/data-model/overall-rel.svg +++ b/docs/_static/data-model/overall-rel.svg @@ -1,28 +1,28 @@ - + moduleName - + CloudifiedNF - -CloudifiedNF + +CloudifiedNF NFDeployment - -NFDeployment + +NFDeployment CloudifiedNF->NFDeployment - - -COMPRISES -1..1 -1..* + + +COMPRISES +1..1 +1..* @@ -33,299 +33,308 @@ NFDeployment->OCloudNamespace - - -DEPLOYED -1..* -1..* + + +DEPLOYED +1..* +1..* ManagedElement - -ManagedElement + +ManagedElement NFDeployment->ManagedElement - - -SERVES -1..* -1..1 + + +SERVES +1..* +1..1 NearRTRICFunction - -NearRTRICFunction + +NearRTRICFunction NFDeployment->NearRTRICFunction - - -SERVES -0..* -0..* + + +SERVES +0..* +0..* OCUCPFunction - -OCUCPFunction + +OCUCPFunction NFDeployment->OCUCPFunction - - -SERVES -0..* -0..* + + +SERVES +0..* +0..* OCUUPFunction - -OCUUPFunction + +OCUUPFunction NFDeployment->OCUUPFunction - - -SERVES -0..* -0..* + + +SERVES +0..* +0..* ODUFunction - -ODUFunction + +ODUFunction NFDeployment->ODUFunction - - -SERVES -0..* -0..* + + +SERVES +0..* +0..* NodeCluster - -NodeCluster + +NodeCluster OCloudSite - -OCloudSite + +OCloudSite NodeCluster->OCloudSite - - -LOCATED -1..* -1..* + + +LOCATED +1..* +1..* OCloudNamespace->NodeCluster - - -DEPLOYED -1..* -1..1 + + +DEPLOYED +1..* +1..1 AntennaModule - -AntennaModule + +AntennaModule Site - -Site + +Site - + AntennaModule->Site - - -INSTALLED -0..* -0..1 + + +INSTALLED +0..* +0..1 AntennaCapability - -AntennaCapability + +AntennaCapability - + AntennaModule->AntennaCapability - - -SERVES -0..* -0..* + + +SERVES +0..* +0..* + + + +NRCellDU + +NRCellDU + + + +AntennaModule->NRCellDU + + +SERVES +1..* +0..* - + ManagedElement->CloudifiedNF - - -DEPLOYED -1..1 -0..1 + + +DEPLOYED +1..1 +0..1 - + ManagedElement->NearRTRICFunction - - -MANAGES -1..1 -0..* + + +MANAGES +1..1 +0..* - + ManagedElement->OCUCPFunction - - -MANAGES -1..1 -0..* + + +MANAGES +1..1 +0..* - + ManagedElement->OCUUPFunction - - -MANAGES -1..1 -0..* + + +MANAGES +1..1 +0..* - + ManagedElement->ODUFunction - - -MANAGES -1..1 -0..* + + +MANAGES +1..1 +0..* ORUFunction - -ORUFunction + +ORUFunction - + ManagedElement->ORUFunction - - -MANAGES -1..1 -0..* + + +MANAGES +1..1 +0..* NRCellCU - -NRCellCU - - - -NRCellDU - -NRCellDU + +NRCellCU NRSectorCarrier - -NRSectorCarrier + +NRSectorCarrier - + NRCellDU->NRSectorCarrier - - -USES -0..1 -0..* + + +USES +0..1 +0..* - + NRSectorCarrier->AntennaCapability - - -USES -0..* -0..1 + + +USES +0..* +0..1 - + OCUCPFunction->NRCellCU - - -PROVIDES -1..1 -0..* + + +PROVIDES +1..1 +0..* - + ODUFunction->NRCellDU - - -PROVIDES -1..1 -0..* + + +PROVIDES +1..1 +0..* - + ODUFunction->NRSectorCarrier - - -PROVIDES -1..1 -0..* + + +PROVIDES +1..1 +0..* Sector - -Sector + +Sector - + Sector->AntennaModule - - -GROUPS -0..1 -0..* + + +GROUPS +0..1 +0..* - + Sector->NRCellDU - - -GROUPS -0..1 -0..* + + +GROUPS +0..1 +0..* diff --git a/docs/_static/dataCloudEvent.svg b/docs/_static/dataCloudEvent.svg index 5a3f029..88d65a8 100644 --- a/docs/_static/dataCloudEvent.svg +++ b/docs/_static/dataCloudEvent.svg @@ -1 +1,25 @@ - \ No newline at end of file + + + + + 1 + + + 2 + + + + + + + 2​ + + + + + + + 1 + 3 + 4 + \ No newline at end of file diff --git a/docs/developer-guide.rst b/docs/developer-guide.rst index ec83aa1..97cf75b 100644 --- a/docs/developer-guide.rst +++ b/docs/developer-guide.rst @@ -84,6 +84,56 @@ 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 +~~~~~~~~~~~~~~~~~~~~ + +These identifiers are uniquely generated values used to identify objects within +Topology & Inventory. + + **NOTE:** To maintain robust design principles, Apps must avoid caching or + depending on topology identifiers (id), as these identifiers are assigned to + entities and relationships for data organization purposes only. Topology + identifiers carry no intrinsic meaning. + +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. + + Topology & Inventory models --------------------------- diff --git a/docs/discover-and-reconciliation-interface-guide.rst b/docs/discover-and-reconciliation-interface-guide.rst index a36661e..5565dc9 100644 --- a/docs/discover-and-reconciliation-interface-guide.rst +++ b/docs/discover-and-reconciliation-interface-guide.rst @@ -58,6 +58,8 @@ between the Site and an AntennaModule. Using the the data producer can create entities that support geographical enrichment. Attributes with null means not set. +Header: + .. code:: json { @@ -67,73 +69,14 @@ enrichment. Attributes with null means not set. "ce_type": "topology-inventory-ingestion-create", "ce_time": "2023-06-12T09:05:00Z", "content-type": "application/json", - "ce_dataschema": "topology-inventory-ingestion:events:create:1.0.0", - "data": { - "entities": [ - { - "o-ran-smo-teiv-equipment:Site": [ - { - "id": "urn:o-ran:smo:teiv:sha512:Site=1F137533843657E9E9DBE60DBD86B045A057DB6D04B6A07AC153", - "attributes": { - "name": "Dublin", - "location": { - "geo-location": { - "latitude": 41.73297, - "longitude": -73.007696 - } - } - } - } - ] - }, - { - "o-ran-smo-teiv-equipment:AntennaModule": [ - { - "id": "urn:o-ran:smo:teiv:sha512:AntennaModule=1FEBF137533843657E9E9DBE60DBD86B045A057DB6D04B6A07AC15323F1906228E93CFA4A1DB37D50252B3AFE6AEC9860E2CEA4A77BB3A25C9EA45DEDA87E765", - "attributes": { - "geo-location": { - "latitude": 41.73297, - "longitude": -73.007696 - } - } - } - ] - } - ], - "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" - } - ] - } - ] - } + "ce_dataschema": "topology-inventory-ingestion:events:create:1.0.0" } -Example of modify enriched Topology & Inventory with geographical data ----------------------------------------------------------------------- - -This example updates an existing Site entity. Using the -:ref:`merge schema ` -the data producer can update entities that support geographical -enrichment. +Payload: .. code:: json - - { - "ce_specversion": "1.0", - "ce_id": "a30e63c9-d29e-46ff-b99a-b63ed83fd234", - "ce_source": "dmi-plugin:nm-1", - "ce_type": "topology-inventory-ingestion-merge", - "ce_time": "2023-06-12T09:05:00Z", - "content-type": "application/json", - "ce_dataschema": "topology-inventory-ingestion:events:merge:1.0.0", - "data": { + { "entities": [ { "o-ran-smo-teiv-equipment:Site": [ @@ -141,13 +84,14 @@ enrichment. "id": "urn:o-ran:smo:teiv:sha512:Site=1F137533843657E9E9DBE60DBD86B045A057DB6D04B6A07AC153", "attributes": { "name": "Dublin", - "location": { - "geo-location": { - "latitude": 52.73297, - "longitude": -84.007696 - } + "geo-location": { + "latitude": 41.73297, + "longitude": -73.007696 } - } + }, + "sourceIds": [ + "urn:oran:smo:teiv:Site=1" + ] } ] }, @@ -157,9 +101,14 @@ enrichment. "id": "urn:o-ran:smo:teiv:sha512:AntennaModule=1FEBF137533843657E9E9DBE60DBD86B045A057DB6D04B6A07AC15323F1906228E93CFA4A1DB37D50252B3AFE6AEC9860E2CEA4A77BB3A25C9EA45DEDA87E765", "attributes": { "geo-location": { - "latitude": 52.73297, - "longitude": -84.007696 - } + "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" + ] } } ] @@ -171,12 +120,100 @@ enrichment. { "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" + "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:Site=1" + ] } ] } ] - } + } + +Example of modify enriched Topology & Inventory with geographical data +---------------------------------------------------------------------- + +This example updates an existing Site entity. Using the +:ref:`merge schema ` +the data producer can update entities that support geographical +enrichment. + +Header: + +.. code:: json + + { + "ce_specversion": "1.0", + "ce_id": "a30e63c9-d29e-46ff-b99a-b63ed83fd234", + "ce_source": "dmi-plugin:nm-1", + "ce_type": "topology-inventory-ingestion-merge", + "ce_time": "2023-06-12T09:05:00Z", + "content-type": "application/json", + "ce_dataschema": "topology-inventory-ingestion:events:merge:1.0.0" + } + +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 + }, + "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", + "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" + ] + } + ] + } + ] } Example of delete enriched data from Topology & Inventory @@ -188,6 +225,8 @@ AntennaModule entity. Using the the data producer can delete entities that support geographical enrichment. +Header: + .. code:: json { @@ -197,27 +236,41 @@ enrichment. "ce_type": "topology-inventory-ingestion-delete", "ce_time": "2023-06-12T09:05:00Z", "content-type": "application/json", - "ce_dataschema": "topology-inventory-ingestion:events:delete:1.0.0", - "data": { - "entities" : [ - { - "o-ran-smo-teiv-equipment:Site": [ - { - "id": "urn:o-ran:smo:teiv:sha512:Site=1F137533843657E9E9DBE60DBD86B045A057DB6D04B6A07AC153" - } - ] - } - ], - "relationships": [ - { - "o-ran-smo-teiv-equipment:ANTENNAMODULE_INSTALLED_AT_SITE": [ - { - "id" : "urn:o-ran:smo:teiv:sha512:ANTENNAMODULE_INSTALLED_AT_SITE=TlJDZWxsRFU6U3ViTmV0d29yaz1FdXJvcGUsU3ViTmV0d29yaz1JcmVs=" - } - ] - } - ] - } + "ce_dataschema": "topology-inventory-ingestion:events:delete:1.0.0" + } + +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" + ] + } + ] + } + ], + "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" + ] + } + ] + } + ] } How to create and produce an event diff --git a/docs/discover-and-reconciliation-interface.rst b/docs/discover-and-reconciliation-interface.rst index b102773..4f4e788 100644 --- a/docs/discover-and-reconciliation-interface.rst +++ b/docs/discover-and-reconciliation-interface.rst @@ -46,9 +46,9 @@ CREATE Headers | | | | | | (`uri`) | | +----------------+--------+-------------------------------------------+--------------------------+-----------------+-------------------+ | ce_type | string | | Event type. It can be one of | - | - | - | -| | | | topology-inventory-ingestion-merge, | | | | -| | | | topology-inventory-ingestion-delete, or | | | | -| | | | topology-inventory-ingestion-create. | | | | +| | | | topology-inventory-ingestion.merge, | | | | +| | | | topology-inventory-ingestion.delete, or | | | | +| | | | topology-inventory-ingestion.create. | | | | +----------------+--------+-------------------------------------------+--------------------------+-----------------+-------------------+ | content-type | string | | Content-type of the data contained | | const | - | - | | | | | within the cloud event. It is | | (`"application/json"`) | | | @@ -75,7 +75,7 @@ CREATE Headers "ce_specversion": "1.0", "ce_id": "a30e63c9-d29e-46ff-b99a-b63ed83fd233", "ce_source": "dmi-plugin:nm-1", - "ce_type": "topology-inventory-ingestion-create", + "ce_type": "topology-inventory-ingestion.create", "ce_time": "2023-06-12T09:05:00Z", "content-type": "application/json", "ce_dataschema": "topology-inventory-ingestion:events:create:1.0.0" @@ -89,26 +89,22 @@ CREATE Payload +======================================================+===============+================================================================+ | (root) | Object | - | +------------------------------------------------------+---------------+----------------------------------------------------------------+ -| data | - | | The data part consists of the actual topology data. It | -| | | | contains all the entities and their associated | -| | | | relationships. | -+------------------------------------------------------+---------------+----------------------------------------------------------------+ -| data.entities | Array | | Entities are topology objects comprising of an id, consumer | +| entities | Array | | Entities are topology objects comprising of an id, consumer | | | | | data, attributes and metadata for each. It contains the id | | | | | only in case of delete cloud event. | +------------------------------------------------------+---------------+----------------------------------------------------------------+ -| | data.entities | Object | | Entities schema is adherent to the entity types and | +| | entities | Object | | Entities schema is adherent to the entity types and | | | . | | | attributes mentioned in the yang modules. For yang modules, | | | : | | | see [Data Models][Data Models]. | +------------------------------------------------------+---------------+----------------------------------------------------------------+ -| data.relationships | Array | | Relationships comprising of an A-side and a B-side for each. | +| relationships | Array | | Relationships comprising of an A-side and a B-side for each. | | | | | The A-side is considered the originating side of the | | | | | relationship; the B-side is considered the terminating side | | | | | of the relationship. The order of A-side and B-side is of | | | | | importance and MUST NOT be changed once defined. It | | | | | contains the id only in case of delete event. | +------------------------------------------------------+---------------+----------------------------------------------------------------+ -| | data.relationships | Object | | Relationship schema is adherent to the relationship types | +| | relationships | Object | | Relationship schema is adherent to the relationship types | | | . | | | mentioned in the yang modules. For yang modules, | | | : | | | see [Data Models][Data Models]. | +------------------------------------------------------+---------------+----------------------------------------------------------------+ @@ -118,96 +114,106 @@ CREATE Payload .. code:: json { - "data": { - "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" + "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 ], - "metadata": { - "trustLevel": "RELIABLE" + "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" + } + ] + }, + { + "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 ], - "metadata": { - "trustLevel": "RELIABLE" + "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" - } - ] - }, - { - "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" - } - ] - } - ] - } + } + ] + } + ], + "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" + ] + } + ] + } + ] } .. _Ingestion Merge: @@ -245,9 +251,9 @@ MERGE Headers | | | | | | (`uri`) | | +----------------+--------+-------------------------------------------+--------------------------+-----------------+-------------------+ | ce_type | string | | Event type. It can be one of | - | - | - | -| | | | topology-inventory-ingestion-merge, | | | | -| | | | topology-inventory-ingestion-delete, or | | | | -| | | | topology-inventory-ingestion-create. | | | | +| | | | topology-inventory-ingestion.merge, | | | | +| | | | topology-inventory-ingestion.delete, or | | | | +| | | | topology-inventory-ingestion.create. | | | | +----------------+--------+-------------------------------------------+--------------------------+-----------------+-------------------+ | content-type | string | | Content-type of the data contained | | const | - | - | | | | | within the cloud event. It is | | (`"application/json"`) | | | @@ -275,7 +281,7 @@ MERGE Headers "ce_specversion": "1.0", "ce_id": "a30e63c9-d29e-46ff-b99a-b63ed83fd234", "ce_source": "dmi-plugin:nm-1", - "ce_type": "topology-inventory-ingestion-merge", + "ce_type": "topology-inventory-ingestion.merge", "ce_time": "2023-06-12T09:05:00Z", "content-type": "application/json", "ce_dataschema": "topology-inventory-ingestion:events:merge:1.0.0" @@ -289,26 +295,22 @@ MERGE Payload +======================================================+===============+================================================================+ | (root) | Object | - | +------------------------------------------------------+---------------+----------------------------------------------------------------+ -| data | - | | The data part consists of the actual topology data. It | -| | | | contains all the entities and their associated | -| | | | relationships. | -+------------------------------------------------------+---------------+----------------------------------------------------------------+ -| data.entities | Array | | Entities are topology objects comprising of an id, consumer | +| entities | Array | | Entities are topology objects comprising of an id, consumer | | | | | data, attributes and metadata for each. It contains the id | | | | | only in case of delete cloud event. | +------------------------------------------------------+---------------+----------------------------------------------------------------+ -| | data.entities | Object | | Entities schema is adherent to the entity types and | +| | entities | Object | | Entities schema is adherent to the entity types and | | | . | | | attributes mentioned in the yang modules. For yang modules, | | | : | | | see [Data Models][Data Models]. | +------------------------------------------------------+---------------+----------------------------------------------------------------+ -| data.relationships | Array | | Relationships comprising of an A-side and a B-side for each. | +| relationships | Array | | Relationships comprising of an A-side and a B-side for each. | | | | | The A-side is considered the originating side of the | | | | | relationship; the B-side is considered the terminating side | | | | | of the relationship. The order of A-side and B-side is of | | | | | importance and MUST NOT be changed once defined. It | | | | | contains the id only in case of delete event. | +------------------------------------------------------+---------------+----------------------------------------------------------------+ -| | data.relationships | Object | | Relationship schema is adherent to the relationship types | +| | relationships | Object | | Relationship schema is adherent to the relationship types | | | . | | | mentioned in the yang modules. For yang modules, | | | : | | | see [Data Models][Data Models]. | +------------------------------------------------------+---------------+----------------------------------------------------------------+ @@ -320,96 +322,106 @@ MERGE Payload .. code:: json { - "data": { - "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" + "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 ], - "metadata": { - "trustLevel": "RELIABLE" + "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" + } + ] + }, + { + "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 ], - "metadata": { - "trustLevel": "RELIABLE" + "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" - } - ] - }, - { - "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" - } - ] - } - ] - } + } + ] + } + ], + "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" + ] + } + ] + } + ] } .. _Ingestion Delete: @@ -447,9 +459,9 @@ DELETE Headers | | | | | | (`uri`) | | +----------------+--------+-------------------------------------------+--------------------------+-----------------+-------------------+ | ce_type | string | | Event type. It can be one of | - | - | - | -| | | | topology-inventory-ingestion-merge, | | | | -| | | | topology-inventory-ingestion-delete, or | | | | -| | | | topology-inventory-ingestion-create. | | | | +| | | | topology-inventory-ingestion.merge, | | | | +| | | | topology-inventory-ingestion.delete, or | | | | +| | | | topology-inventory-ingestion.create. | | | | +----------------+--------+-------------------------------------------+--------------------------+-----------------+-------------------+ | content-type | string | | Content-type of the data contained | | const | - | - | | | | | within the cloud event. It is | | (`"application/json"`) | | | @@ -476,7 +488,7 @@ DELETE Headers "ce_specversion": "1.0", "ce_id": "a30e63c9-d29e-46ff-b99a-b63ed83fd235", "ce_source": "dmi-plugin:nm-1", - "ce_type": "topology-inventory-ingestion-delete", + "ce_type": "topology-inventory-ingestion.delete", "ce_time": "2023-06-12T09:05:00Z", "content-type": "application/json", "ce_dataschema": "topology-inventory-ingestion:events:delete:1.0.0" @@ -490,26 +502,22 @@ DELETE Payload +======================================================+===============+================================================================+ | (root) | Object | - | +------------------------------------------------------+---------------+----------------------------------------------------------------+ -| data | - | | The data part consists of the actual topology data. It | -| | | | contains all the entities and their associated | -| | | | relationships. | -+------------------------------------------------------+---------------+----------------------------------------------------------------+ -| data.entities | Array | | Entities are topology objects comprising of an id, consumer | +| entities | Array | | Entities are topology objects comprising of an id, consumer | | | | | data, attributes and metadata for each. It contains the id | | | | | only in case of delete cloud event. | +------------------------------------------------------+---------------+----------------------------------------------------------------+ -| | data.entities | Object | | Entities schema is adherent to the entity types and | +| | entities | Object | | Entities schema is adherent to the entity types and | | | . | | | attributes mentioned in the yang modules. For yang modules, | | | : | | | see [Data Models][Data Models]. | +------------------------------------------------------+---------------+----------------------------------------------------------------+ -| data.relationships | Array | | Relationships comprising of an A-side and a B-side for each. | +| relationships | Array | | Relationships comprising of an A-side and a B-side for each. | | | | | The A-side is considered the originating side of the | | | | | relationship; the B-side is considered the terminating side | | | | | of the relationship. The order of A-side and B-side is of | | | | | importance and MUST NOT be changed once defined. It | | | | | contains the id only in case of delete event. | +------------------------------------------------------+---------------+----------------------------------------------------------------+ -| | data.relationships | Object | | Relationship schema is adherent to the relationship types | +| | relationships | Object | | Relationship schema is adherent to the relationship types | | | . | | | mentioned in the yang modules. For yang modules, | | | : | | | see [Data Models][Data Models]. | +------------------------------------------------------+---------------+----------------------------------------------------------------+ @@ -526,14 +534,24 @@ DELETE Payload { "o-ran-smo-teiv-equipment:AntennaModule": [ { - "id": "urn:oran:smo:teiv:AntennaModule=1" + "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" + "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" + ] } ] } @@ -542,14 +560,26 @@ DELETE Payload { "o-ran-smo-teiv-equipment:ANTENNAMODULE_INSTALLED_AT_SITE": [ { - "id": "urn:sha512:TlJDZWxsRFU6U3ViTmV0d29yaz1FdXJvcGUsU3ViTmV0d29yaz1JcmVs=" + "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=" + "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" + ] } ] } diff --git a/docs/groupings.rst b/docs/groupings.rst new file mode 100644 index 0000000..f60a95d --- /dev/null +++ b/docs/groupings.rst @@ -0,0 +1,355 @@ +.. 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 OpenInfra Foundation Europe. All Rights Reserved + +Topology grouping +################# + +Topology groups provide the capability to create user-defined +collections of topology entities and/or relationships of any +type. Groups can be either *static* or *dynamic* based on how +they are created. + + **Static group**: This is a collection of topology identifiers + specified by the user. + + **Dynamic group**: This holds a single resource query specified + by the user, which, when resolved, fetches the desired collection + of topology entities or relationships. + +Creating topology groups +------------------------ + +The following describes how to create topology groups for entities and relationships +in both static and dynamic ways. + +After a successful creation, a group ID is generated +and returned in the response. This ID should be stored as it is used when resolving +a topology group (described under +:ref:`Resolving group members ` + + + **NOTE:** There is no validation done during the creation of topology groups, + this is done during the group resolution. + +Static groups +============= +To create a static group, use: + POST /groups + +See the following table for a description of the payload required +when creating static groups. + +**Static group payload** + ++-----------------+---------------------------------------------+--------------+ +| **Parameter** | **Description** | **Required** | ++=================+=============================================+==============+ +| name | | The desired name of the group (this is | True | +| | | not unique). | | ++-----------------+---------------------------------------------+--------------+ +| type | The group type (`static` in this case). | True | ++-----------------+---------------------------------------------+--------------+ +| providedMembers | | A list containing the identities of the | True | +| | | desired members (entities or | | +| | | relationships) in the model format. | | ++-----------------+---------------------------------------------+--------------+ + +**Example:** Create a static group with two provided members: + +:: + + POST 'https:///topology-inventory//groups' + Content-Type: application/json + Accept: application/json + +.. code-block:: json + + { + "name": "cell-filter-group-1", + "type": "static", + "providedMembers": [ + { + "o-ran-smo-teiv-ran:NRCellDU": [ + { + "id": "urn:3gpp:dn:ManagedElement=1,ODUFunction=1,NRCellDU=1" + } + ] + }, + { + "o-ran-smo-teiv-ran:ODUFunction": [ + { + "id": "urn:3gpp:dn:ManagedElement=1,ODUFunction=1" + } + ] + } + ] + } + +**NOTE:** + - Static groups can include a maximum of 10,000 provided members, + with a limit of 2,000 members during creation and 2,000 in each + subsequent merge operation. + - The performance of static groups is related to the number of members. + If a group with a large number of members is required, it is recommended + to use dynamic groups in combination with classifiers for best performance. + - It is not possible to create a group of groups. + +Dynamic groups +============== + +To create a dynamic group, use: + POST /groups + +See the following table for a description of the payload required +when creating dynamic groups. + +**Dynamic group payload** + ++-------------------------------+------------------------------------------------+--------------------------------------------------+ +| **Parameter** | **Description** | **Required** | ++===============================+================================================+==================================================+ +| name | | The desired name of the group (this is not | True | +| | | unique). | | ++-------------------------------+------------------------------------------------+--------------------------------------------------+ +| type | The group type (`dynamic` in this case). | True | ++-------------------------------+------------------------------------------------+--------------------------------------------------+ +| criteria | | The set of parameters needed to specify the | True | +| | | 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: | | +| | | | | ++-------------------------------+------------------------------------------------+--------------------------------------------------+ +| criteria.domain | | This is the topology domain. Use TEIV if not | True | +| | | known. | | ++-------------------------------+------------------------------------------------+--------------------------------------------------+ +| 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. | | ++-------------------------------+------------------------------------------------+--------------------------------------------------+ +| criteria.relationshipTypeName | | The relationship type, for example, | | Required only when *criteria.queryType* is | +| | | `ODUFUNCTION_PROVIDES_NRCELLDU`. | | `getRelationshipsByType` | ++-------------------------------+------------------------------------------------+--------------------------------------------------+ +| criteria.targetFilter | | Use the targetFilter parameter to narrow | False | +| | | down the fields to return. This is similar | | +| | | to the SELECT keyword in an SQL statement. | | ++-------------------------------+------------------------------------------------+--------------------------------------------------+ +| criteria.scopeFilter | | Use the scopeFilter parameter to filter the | False | +| | | results using specific criteria. This is | | +| | | similar to the WHERE keyword in an SQL | | +| | | statement. | | ++-------------------------------+------------------------------------------------+--------------------------------------------------+ + + +**Example:** Create a dynamic group of *NRCellDU* entities that have a *cellLocalId* +equal to 1: + +:: + + POST 'https:///topology-inventory//groups' + Content-Type: application/json + Accept: application/json + +.. code-block:: json + + { + "name": "cell-filter-group-2", + "type": "dynamic", + "criteria": { + "queryType": "getEntitiesByDomain", + "domain": "RAN", + "targetFilter": "/NRCellDU/attributes(nCI)", + "scopeFilter": "/NRCellDU/attributes[@cellLocalId=1]" + } + } + +**NOTE:** For dynamic groups, there is no limit to the amount of members +returned when resolving the group. + +Querying topology groups +------------------------ + +Fetching groups +=============== + +To fetch a list of all groups (static or dynamic), use: + GET /groups + +**Example:** Get all groups: + +:: + + GET 'https:///topology-inventory//groups' + Accept: application/json + + +The user can filter the result by specifying a group name as a query parameter. +This returns a list of all groups that exactly match the provided name string. + + **NOTE:** The topology group 'name' parameter is not unique. + +**Example:** Get all groups with names that match *cell-filter-group*: + +:: + + GET 'https:///topology-inventory//groups?name=cell-filter-group' + Accept: application/json + +To get a specific group by its *groupId*, use: + GET /groups/{groupId} + +**Example:** Fetch a group with groupId *urn:o-ran:smo:teiv:group=123e4567-e89b-12d3-a456-426614174000*: + +:: + + GET 'https:///topology-inventory//groups/urn:o-ran:smo:teiv:group=123e4567-e89b-12d3-a456-426614174000' + Accept: application/json + +Resolving group members +======================= +To get the members of a group using its *groupId*, use: + GET /groups/{groupId}/members + +**Example:** Get the members of a group with groupId +*urn:o-ran:smo:teiv:group=123e4567-e89b-12d3-a456-426614174000*: + +:: + + GET 'https:///topology-inventory//groups/urn:o-ran:smo:teiv:group=123e4567-e89b-12d3-a456-426614174000/members' + Accept: application/json + + +**NOTE:** This query returns only the IDs of the topology entities or relationships +that are present in your inventory. The members provided by the user (in the case of +static groups) that are invalid or not present are discarded in the response. + +To get the provided members of a **static** group using its *groupId*, use: + GET /groups/{groupId}/provided-members + +This fetches all members provided by the user including members that are invalid or not present +in your inventory. + +**Example:** Get the provided members of a static group with groupId +*urn:o-ran:smo:teiv:group=123e4567-e89b-12d3-a456-426614174000*: + +:: + + GET 'https:///topology-inventory//groups/urn:o-ran:smo:teiv:group=123e4567-e89b-12d3-a456-426614174000/provided-members' + Accept: application/json + +The provided members in a static group can be filtered using the *status* query parameter. + +**Example:** Get the provided members of a static group with groupId +*urn:o-ran:smo:teiv:group=123e4567-e89b-12d3-a456-426614174000* that are *not-present*: + +:: + + GET 'https:///topology-inventory//groups/urn:o-ran:smo:teiv:group=123e4567-e89b-12d3-a456-426614174000/provided-members?status=not-present' + Accept: application/json + +**NOTE:** The accepted values for 'status' are *present*, *not-present*, and *invalid*. +See the following 'Topology status and descriptions' table for more information. + +**Topology status and descriptions** + ++-------------+-----------------------------------------------------------------------------------+ +| **Status** | **Description** | ++=============+===================================================================================+ +| present | Entity or relationship IDs that currently exist in your topology. | ++-------------+-----------------------------------------------------------------------------------+ +| not-present | Entity or relationship IDs that do not exist in your topology. | ++-------------+-----------------------------------------------------------------------------------+ +| invalid | Entity or relationship IDs of a topology type that does not match the TIES model. | ++-------------+-----------------------------------------------------------------------------------+ + + +Modifying topology groups +------------------------- + +Update a group name +=================== + +To update the name of a topology group specified by its *groupId*, use: + PUT /groups/{groupId}/name + +**Example:** Update the name of a group with groupId +*urn:o-ran:smo:teiv:group=123e4567-e89b-12d3-a456-426614174000*: + +:: + + PUT 'https:///topology-inventory//groups/urn:o-ran:smo:teiv:group=123e4567-e89b-12d3-a456-426614174000/name' + Content-Type: application/json + +.. code-block:: json + + { + "name": "cell-filter-group-5" + } + +Update the members in a group +============================= + +To merge or remove members in an existing topology group, use: + POST /groups/{groupId}/provided-members-operations + +**NOTE:** This operation is applicable for static groups only. + +**Example:** Merge members of a group with groupId +*urn:o-ran:smo:teiv:group=123e4567-e89b-12d3-a456-426614174000*: + +:: + + POST 'https:///topology-inventory//groups/urn:o-ran:smo:teiv:group=123e4567-e89b-12d3-a456-426614174000/provided-members-operations' + Content-Type: application/json + Accept: application/json + +.. code-block:: json + + { + "operation": "merge", + "providedMembers": [ + { + "o-ran-smo-teiv-ran:NRCellDU": [ + { + "id": "urn:3gpp:dn:ManagedElement=1,ODUFunction=1,NRCellDU=1" + } + ] + } + ] + } + +**Example:** Remove members from a group with groupId +*urn:o-ran:smo:teiv:group=123e4567-e89b-12d3-a456-426614174000*: + +:: + + POST 'https:///topology-inventory//groups/urn:o-ran:smo:teiv:group=123e4567-e89b-12d3-a456-426614174000/provided-members-operations' + Content-Type: application/json + Accept: application/json + +.. code-block:: json + + { + "operation": "remove", + "providedMembers": [ + { + "o-ran-smo-teiv-ran:NRCellDU": [ + { + "id": "urn:3gpp:dn:ManagedElement=1,ODUFunction=1,NRCellDU=1" + } + ] + } + ] + } \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index 9234018..85cc8f0 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -19,6 +19,7 @@ to share and operate on a common view of the topology. ./developer-guide.rst ./query-api-examples.rst ./classifiers-and-decorators.rst + ./groupings.rst ./data-models-guide.rst ./discover-and-reconciliation-interface-guide.rst ./discover-and-reconciliation-interface.rst diff --git a/docs/query-api-examples.rst b/docs/query-api-examples.rst index 66edffe..319b647 100644 --- a/docs/query-api-examples.rst +++ b/docs/query-api-examples.rst @@ -119,3 +119,38 @@ in the request as follows: **Note:** If the targetFilter is not used here, the result contains all entities and relationships that matches the condition in the RAN domain. + +Querying on geographical information examples +--------------------------------------------- + +Topology & Inventory supports querying entities based on geographical information +by updating the filters. Use the "Well-Known Text" (WKT) representation of geometry +to specify geometry objects. The WKT representation of coordinate systems is a text +markup language standard for representing vector geometry objects. For more information, +see the `WKT documentation `_ + + **NOTE:** This filter option is restricted to entities that have been enriched with geographical data. + +Topology & Inventory supports the following geometric objects: + +**POINT:** This can be used with the *withinMeters* function. It requires the latitude +and longitude of the point and then a range in meters. It returns the desired objects within the provided +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)] +``` + +**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))')] +``` + + **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 2134393..a7279e4 100644 --- a/docs/supported-filter-options.rst +++ b/docs/supported-filter-options.rst @@ -43,6 +43,10 @@ be retrieved and filtered using the /attributes. | | To return the ids for all instances of | RAN | ODUFunction | | | | All ids of every | | | the entityTypeName used in the query. | | | | | | ODUFunction | +------------------------------------------+--------+----------------+--------------+------------------------+------------------------+ +| | To return the metadata of every | RAN | ODUFunction | /metadata | | | All ODUFunctions | +| | instance of the entitytypeName used in | | | | | | with metadata | +| | the query. | | | | | | ++------------------------------------------+--------+----------------+--------------+------------------------+------------------------+ | | To return all attributes of every | RAN | ODUFunction | /attributes | | | All ODUFunctions | | | instance of the entityTypeName used | | | | | | with every attribute | | | in the query. | | | | | | @@ -64,10 +68,16 @@ be retrieved and filtered using the /attributes. +------------------------------------------+--------+----------------+--------------+------------------------+------------------------+ | | To return the ids for all instances of | RAN | ODUFunction | | /sourceIds | | Unique set of ids | | | the entityTypeName used in the query, | | | | [contains (@item, | | of ODUFunctions, | -| | that matches the given | | | | 'SubNetwork=Ireland')] | | where sourceIds | +| | that partially matches the given | | | | 'SubNetwork=Ireland')] | | where sourceIds | | | property in the *scopeFilter* | | | | | | contains | | | parameter. | | | | | | *SubNetwork=Ireland* | +------------------------------------------+--------+----------------+--------------+------------------------+------------------------+ +| | To return the metadata for all | RAN | ODUFunction | | /metadata | | Unique set of | +| | instances of the entityTypeName used | | | | [@reliabilityIndicator | | metadata of | +| | in the query, that matches the given | | | | ='OK'] | | ODUFunctions, where | +| | property in the *scopeFilter* | | | | | | reliabilityIndicator | +| | parameter | | | | | | equals OK | ++------------------------------------------+--------+----------------+--------------+------------------------+------------------------+ | | To return the ids for all instances of | RAN | ODUFunction | | /attributes | | Unique set of ids of | | | the entityTypeName used in the query, | | | | [@gNBId | | ODUFunctions,where | | | that matches the given attributes in | | | | Length=3 and | | the gNBIdLength | @@ -119,8 +129,42 @@ The *entityTypeName* is used as the root of the queries. | | | | | /managed-by-managedElement | | | | | | | [@id='urn\:3gpp:dn: | | | | | | | ManagedElement=2'] | | ++------------------------------------------+-------------+----------------+--------------+----------------------------+--------------------------------------------------+ +| | 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. | +| | *scopeFilter* parameter. | | | | 500.5)] | | +------------------------------------------+-------------+----------------+--------------+----------------------------+--------------------------------------------------+ + **/domains/{domainName}/entities** + ++------------------------------------------+-------------+----------------+-------------------------------------------+--------------------------------------------------+ +| Use case | domainName | targetFilter | scopeFilter | Query result | ++------------------------------------------+-------------+----------------+-------------------------------------------+--------------------------------------------------+ +| | To return the ids of all entities in a | RAN | | /managed-by-managedElement | | All entities that are managed by any | +| | given domain related by an association | | | | | ManagedElement. | ++------------------------------------------+-------------+----------------+-------------------------------------------+--------------------------------------------------+ +| | To return the ids of all entities in a | RAN | /ODUFunction | /managed-by-managedElement | | All ODUFunction entities that are managed by | +| | given domain related by an association | | | [@id = 'urn :3gpp :dn: ManagedElement=1'] | | the ManagedElement | +| | to another entity specified by its | | | | | *urn:3gpp:dn: ManagedElement=1*. | +| | *id*. | | | | | ++------------------------------------------+-------------+----------------+-------------------------------------------+--------------------------------------------------+ +| | To return the attributes for all | RAN | /attributes | /managed-by-managedElement [@id= | | All entities managed by the | +| | entities in a given domain related by | | | 'urn: 3gpp:dn: ManagedElement=1'] | | | ManagedElement *urn:3gpp:dn:ManagedElement=1* | +| | one or more associations to other | | | | | or *urn:3gpp:dn: ManagedElement=2*, and | +| | entities specified by their *id*. | | | /managed-by-managedElement | | provides NRCellDU *urn:3gpp:dn:* | +| | | | [@id='urn: 3gpp:dn: ManagedElement=2'] ; | | *ManagedElement=1, NRCellDU=2*. | +| | | | | | +| | | | /provided-nrCellDu [@id='urn: 3gpp | | +| | | | :dn:ManagedElement=1, NRCellDU=2'] | | ++------------------------------------------+-------------+----------------+-------------------------------------------+--------------------------------------------------+ +| | To return the ids of all entities in a | EQUIPMENT | | /grouped-by-sector/attributes[sectorId=1] | | All entities that grouped by a Sector whose | +| | given domain related by one or more | | | | | sectorId equals 1 | +| | associations to other entities whose | | | | | +| | attributes match a specified | | | | | +| | *scopeFilter* query. | | | | | ++------------------------------------------+-------------+----------------+-------------------------------------------+--------------------------------------------------+ Querying entities for relationships ----------------------------------- @@ -186,7 +230,7 @@ relationship with id *rel1* in the *REL_OAM_RAN* domain: GET https:///topology-inventory//domains/REL_OAM_RAN/relationship-types/MANAGEDELEMENT_MANAGES_ORUFUNCTION/relationships/rel1 Querying on classifiers and decorators -************************************** +-------------------------------------- This functionality is supported by the following endpoints @@ -214,7 +258,7 @@ This functionality is supported by the following endpoints +-------------------------------------------+--------+--------+-----------------------+------------------------------------------+ | | Return all related entity IDs that are | RAN | | /decorators[contains( | | All the entity IDs that are exactly | | | exactly matched with key parameter | | | @odu-function-model | | matched with | -| | where the value of the decorator is | | | :textdata, "")] | | "odu-function-model:textdata as key | +| | where the value of the decorator is | | | :textdata, '')] | | "odu-function-model:textdata as key | | | unknown with given domain name. | | | | | of the decorator in RAN domain. | +-------------------------------------------+--------+--------+-----------------------+------------------------------------------+ @@ -222,7 +266,7 @@ This functionality is supported by the following endpoints :: - GET https:///topology-inventory//domains/REL_OAM_RAN/entities?scopeFilter=/decorators[@o-ran-smo-teiv-ran:textdata = 'Stockholm'] + GET https:///topology-inventory//domains/REL_OAM_RAN/entities?scopeFilter=/decorators[@o-ran-smo-teiv-ran:textdata = 'Stockholm'] **Result** @@ -306,11 +350,11 @@ This functionality is supported by the following endpoints | | | | | | | the classifiers partially contain "Ind". | +-------------------------------------+--------------+--------------+---------------------------+--------------------------------------------------------+---------------------------------------------------+ -**Example:** Get the entities and classifiers where the classifier contains the text *Indoor* +**Example:** Get the entities and classifiers where the classifier contains the text *Rural* :: - GET https:///topology-inventory//domains/RAN/entity-types/NRCellDU/entities?targetFilter=/classifiers&scopeFilter=/classifiers[contains(@item, 'Rural')] + GET https:///topology-inventory//domains/RAN/entity-types/NRCellDU/entities?targetFilter=/classifiers&scopeFilter=/classifiers[contains(@item, 'Rural')] **Result** @@ -429,4 +473,129 @@ This functionality is supported by the following endpoints "href": "/domains/REL_OAM_RAN/relationship-types/MANAGEDELEMENT_MANAGES_ODUFUNCTION/relationships?offset=0&limit=500&scopeFilter=/classifiers[@item = 'o-ran-smo-teiv-ran:Rural']&targetFilter=/classifiers" }, "totalCount": 1 - } \ No newline at end of file + } + +Querying on Geographical Information +------------------------------------ + +This functionality is supported by the following endpoints: + +**/domains/{domainName}/entity-types/{entityTypeName}/entities** + +The *entityTypeName* is used as the root of the queries. Use the "Well-Known Text" (WKT) representation of geometry to +specify geometry objects. See the `WKT documentation `_ for more information. + +For supported geometry objects, see `Querying on geographical information <#capabilities/topology-inventory/developer-guide?chapter=querying-on-geographical-information>`_. + ++------------------------------------------+---------------+----------------+-------------------------------------------+--------------------------------------------------+ +| 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))')] | | | ++------------------------------------------+---------------+----------------+-------------------------------------------+--------------------------------------------------+ +| | 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)). | ++------------------------------------------+---------------+----------------+-------------------------------------------+--------------------------------------------------+ +| | 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 | +| | | | | | respectively. | ++------------------------------------------+---------------+----------------+-------------------------------------------+--------------------------------------------------+ + +**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))')] + +**Result** + +.. code-block:: json + + { + "items": [ + { + "o-ran-smo-teiv-equipment:AntennaModule": [ + { + "id": "urn:o-ran:smo:teiv:sha512:AntennaModule=971FCD28D02B78DDD982611639A0957140339C5522EAAF3FBACA1B8308CF7B0A870CFA80AE04E259805B2A2CB95E263261309883B4D4BF50183FA17AFBA47EA7" + } + ] + } + ], + "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))')]" + }, + "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))')]" + }, + "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))')]" + }, + "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))')]" + }, + "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))')]" + }, + "totalCount": 1 + } + +**/domains/{domainName}/entities** + ++------------------------------------------+----------------+-------------------------------------------+--------------------------------------------------+ +| 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))')] | | | ++------------------------------------------+----------------+-------------------------------------------+--------------------------------------------------+ +| | 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)). | ++------------------------------------------+----------------+-------------------------------------------+--------------------------------------------------+ +| | 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 | +| | point. | | | | respectively. | ++------------------------------------------+----------------+-------------------------------------------+--------------------------------------------------+ + +**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: + +:: + + GET https:///topology-inventory//domains/EQUIPMENT/entities?scopeFilter=/attributes[withinMeters(@geo-location, 'POINT(49.40199 68.94199)', 500)] + +**Result** + +.. code-block:: json + + { + "items": [ + { + "o-ran-smo-teiv-equipment:AntennaModule": [ + { + "id": "urn:o-ran:smo:teiv:sha512:AntennaModule=971FCD28D02B78DDD982611639A0957140339C5522EAAF3FBACA1B8308CF7B0A870CFA80AE04E259805B2A2CB95E263261309883B4D4BF50183FA17AFBA47EA7" + } + ] + } + ], + "self": { + "href": "/domains/EQUIPMENT/entities?offset=0&limit=500&scopeFilter=/attributes[withinMeters(@geo-location, 'POINT(49.40199 68.94199)', 500)]" + }, + "first": { + "href": "/domains/EQUIPMENT/entities?offset=0&limit=500&scopeFilter=/attributes[withinMeters(@geo-location, 'POINT(49.40199 68.94199)', 500)]" + }, + "prev": { + "href": "/domains/EQUIPMENT/entities?offset=0&limit=500&scopeFilter=/attributes[withinMeters(@geo-location, 'POINT(49.40199 68.94199)', 500)]" + }, + "next": { + "href": "/domains/EQUIPMENT/entities?offset=0&limit=500&scopeFilter=/attributes[withinMeters(@geo-location, 'POINT(49.40199 68.94199)', 500)]" + }, + "totalCount": 1 + } -- 2.16.6