docs/geographical-location-enrichment-guide.rst

.. 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

Geographical enrichment guide
#############################

Geographical Enrichment Guide Overview
======================================

In this guide, we explore how to use the Geographical Location
Enrichment API to enrich Topology & Inventory with geographical data.

Geographical enrichment
=======================

Geographical enrichment is the adding, modifying, and removing of
geographical entities that supports geographical information.
Geographical entities are associated to topology data. The following
geographical entities support geographical enrichment:

-  Sector
-  AntennaModule
-  Site

For information on the entity types and their supported relationships,
see the :doc:`Data Models </data-models-guide>`.

The format of the geographical enrichment message is CloudEvents.
Topology & Inventory uses `CloudEvents
Kafka® <https://cloudevents.github.io/sdk-java/kafka.html>`__ version
2.5.x. The link provides a sample CloudEvents implementation in Java®.
CloudEvents SDKs also supports other languages. See
`CloudEvents <https://cloudevents.io/>`__.

The “data” element consists of the actual topology and inventory data.
It contains all the geographical entities and their associated
relationships in application/json format, and each entity and
relationships are represented in application/yang-data+json format.

CloudEvents attributes are validated against the :doc:`Data Models
</data-models-guide>`. If there
is an unknown attribute in the CloudEvents, Topology & Inventory does
not drop the whole event but parses and persists only valid attributes,
and unknown parts are logged and ignored. If an empty or bad payload is
sent, the data is not persisted.

The value of non-mandatory fields can be deleted by sending a merge
request to set it to null. Null means that the value is not set.

Example of enrich Topology & Inventory with geographical data
-------------------------------------------------------------

This example creates a new topology Site entity and a relationship
between the Site and an AntennaModule. Using the
:ref:`create schema <Ingestion Create>`
the data producer can create entities that support geographical
enrichment. Attributes with null means not set.

.. code:: json

   {
       "ce_specversion": "1.0",
       "ce_id": "a30e63c9-d29e-46ff-b99a-b63ed83fd233",
       "ce_source": "dmi-plugin:nm-1",
       "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"
               }
             ]
           }
         ]
       }
   }

Example of modify enriched Topology & Inventory with geographical data
----------------------------------------------------------------------

This example updates an existing Site entity. Using the
:ref:`merge schema <Ingestion Merge>`
the data producer can update entities that support geographical
enrichment.

.. 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": [
             {
               "id": "urn:o-ran:smo:teiv:sha512:Site=1F137533843657E9E9DBE60DBD86B045A057DB6D04B6A07AC153",
               "attributes": {
                 "name": "Dublin",
                 "location": {
                   "geo-location": {
                     "latitude": 52.73297,
                     "longitude": -84.007696
                   }
                 }
               }
             }
           ]
         },
         {
           "o-ran-smo-teiv-equipment:AntennaModule": [
             {
               "id": "urn:o-ran:smo:teiv:sha512:AntennaModule=1FEBF137533843657E9E9DBE60DBD86B045A057DB6D04B6A07AC15323F1906228E93CFA4A1DB37D50252B3AFE6AEC9860E2CEA4A77BB3A25C9EA45DEDA87E765",
               "attributes": {
                 "geo-location": {
                   "latitude": 52.73297,
                   "longitude": -84.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"
             }
           ]
         }
       ]
     }
   }

Example of delete enriched data from Topology & Inventory
---------------------------------------------------------

This example deletes a topology Site entity and its relationship to an
AntennaModule entity. Using the
:ref:`delete schema <Ingestion Delete>`
the data producer can delete entities that support geographical
enrichment.

.. code:: json

   {
       "ce_specversion": "1.0",
       "ce_id": "a30e63c9-d29e-46ff-b99a-b63ed83fd235",
       "ce_source": "dmi-plugin:nm-1",
       "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="
                   }
               ]
             }
           ]
       }
   }

How to create and produce an event
==================================

To create and produce an event, you can use the `CloudEventBuilder.v1
and
KafkaProducer <https://cloudevents.github.io/sdk-java/kafka.html>`__.
The link provides a sample CloudEvents implementation in Java.
CloudEvents SDKs also supports other languages. See
`CloudEvents <https://cloudevents.io/>`__.

Troubleshooting
===============

If CloudEvents were sent but no data was persisted, check validation
failures and logs. Update the CloudEvent based on the logs and send it again.