Merge "TEIV: Update docs"

o-ran-sc · Sep 17, 2024 · 96184aa · 96184aa
2 parents 1660660 + b11cafe
commit 96184aa
Show file tree

Hide file tree

Showing 8 changed files with 553 additions and 122 deletions.
diff --git a/docs/_static/dataCloudEvent.svg b/docs/_static/dataCloudEvent.svg
diff --git a/docs/classifiers-and-decorators.rst b/docs/classifiers-and-decorators.rst
@@ -0,0 +1,111 @@
+.. 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
+
+Classifiers and decorators
+##########################
+
+Classifiers and decorators are user defined tags that represent
+attributes of a topology object. Classifiers and decorators are added
+to a topology object through a REST API. They can be used in querying
+topology.
+
+Classifier (also known as tag or label) permits the association of a
+well defined user specified string with an entity or relationship.
+
+Decorators are key-value pairs that can be associated with topology
+objects. The type of the value is defined by the user in the schema
+which declares the decorator. It can be either a string, number or
+a boolean.
+
+Before classifying the entities or the relationships, the schema
+must be created and validated. The schema can be created, by using
+its own endpoint, with a :doc:`Yang Module <data-models-guide>`.
+The user must provide a unique module name, to avoid collision of
+multiple users access that are defining classifiers and decorators.
+The schema cannot be modified later on but only deleted and recreated,
+if needed. When a schema is successfully created and validated, the user
+can add the classifiers to the entities or relationships. Classifiers and
+decorators have their own endpoints and the request type, to be used,
+is POST. By default, maximum mergable classifiers and decorators are 100.
+That means the sum of the given entities and the relationships in a single
+request cannot exceed 100. Default value can be changed with using the
+site values of the application at .Values.consumerData.batchSize using
+an integer value.
+
+How to use classifiers and decorators
+-------------------------------------
+
+ 1. Create a schema with the schemas endpoint using :doc:`Yang Module
+    <data-models-guide>`. After the successful schema creation, the
+    topology objects are ready to be classified.
+ 2. Assign classifiers and/or decorators to the entities and/or relationships.
+ 3. Search classifiers and/or decorators by using :doc:`queries
+    <supported-filter-options>`.
+
+Classifiers
+===========
+
+Classifiers support the following two types of 'operation', which must be
+identified in the body of the request:
+
+ * merge: defined classifiers can be applied to entities and relationships
+   within a single request.
+ * delete: existing tagged classifiers can be removed.
+
+**Example:**
+
+In this example, user is classifying two given entity IDs and a single
+relationship ID with a single request.
+
+.. code:: json
+
+   {
+     "operation": "merge",
+     "classifiers": [
+       "module-x:Outdoor",
+       "module-y:Rural",
+       "module-z:Weekend"
+     ],
+     "entityIds": [
+       "urn:3gpp:dn:ManagedElement=1,GNBDUFunction=1,NRCellDU=1",
+       "urn:3gpp:dn:ManagedElement=1,GNBDUFunction=1,NRCellDU=2"
+     ],
+     "relationshipIds": [
+       "urn:o-ran:smo:teiv:sha512:NRCELLDU_USES_NRSECTORCARRIER=CA576F4716C36A1BD1C506DCB58418FC731858D3D3F856F536813A8C4D3F1CC21292E506815410E04496D709D96066EBC0E4890DEFC3789EDC4BD9C28DA1D52B"
+     ]
+   }
+
+Decorators
+==========
+
+Decorators support the following two types of 'operations', which must be
+identified in the body of the request:
+
+ * merge: existing decorators can be updated or applied to entities and
+   relationships within a single request.
+ * delete: existing tagged decorators can be removed.
+
+**Example:**
+
+In this example, user is tagging decorators with two given entity IDs and
+a single relationship ID with a single request.
+
+.. code:: json
+
+   {
+     "operation": "merge",
+     "decorators": {
+       "module-x:location": "Stockholm",
+       "module-y:vendor": "Ericsson"
+     },
+     "entityIds": [
+       "urn:3gpp:dn:ManagedElement=1,GNBDUFunction=1,NRCellDU=1",
+       "urn:3gpp:dn:ManagedElement=1,GNBDUFunction=1,NRCellDU=2"
+     ],
+     "relationshipIds": [
+       "urn:o-ran:smo:teiv:sha512:NRCELLDU_USES_NRSECTORCARRIER=CA576F4716C36A1BD1C506DCB58418FC731858D3D3F856F536813A8C4D3F1CC21292E506815410E04496D709D96066EBC0E4890DEFC3789EDC4BD9C28DA1D52B"
+     ]
+   }
+
diff --git a/docs/developer-guide.rst b/docs/developer-guide.rst
@@ -95,11 +95,12 @@ submodules. Management instance data is a graph of objects which have
 attributes (see the **schema** in the data models).
 
 The :doc:`Topology & Inventory Data Models <data-models-guide>` includes:
-- Modules for each supported domain that describe the structure of the
-managed objects within it as well as any relationships between them. -
-Modules that describe cross-domain relationships. - Modules that define
-proprietary extensions and types used to describe the structure of
-objects and attributes within the domains.
+
+ - Modules for each supported domain that describe the structure of the
+   managed objects within it as well as any relationships between them.
+ - Modules that describe cross-domain relationships.
+ - Modules that define proprietary extensions and types used to describe
+   the structure of objects and attributes within the domains.
 
 The following sample diagram shows some managed objects and their
 relationships in the RAN domain.
@@ -141,15 +142,15 @@ Supported domains
 |                                   | | comprises cloud infrastructure and deployment       |
 |                                   | | aspects that can be used in the topology model.     |
 +-----------------------------------+-------------------------------------------------------+
-| EQUIPMENT_TO_RAN                  | | This model contains the topology relations          |
+| REL_EQUIPMENT_RAN                 | | This model contains the topology relations          |
 |                                   | | between Equipment and RAN.                          |
 +-----------------------------------+-------------------------------------------------------+
-| OAM_TO_RAN                        | | This model contains the topology relations          |
+| REL_OAM_RAN                       | | This model contains the topology relations          |
 |                                   | | between O&M and RAN.                                |
 +-----------------------------------+-------------------------------------------------------+
-| CLOUD_TO_RAN                      | | This model contains the RAN Cloud to RAN Logical    |
+| REL_CLOUD_RAN                     | | This model contains the RAN Cloud to RAN Logical    |
 |                                   | | topology relations.                                 |
 +-----------------------------------+-------------------------------------------------------+
-| OAM_TO_CLOUD                      | | This model contains the RAN O&M to Cloud            |
+| REL_OAM_CLOUD                     | | This model contains the RAN O&M to Cloud            |
 |                                   | | topology relations.                                 |
 +-----------------------------------+-------------------------------------------------------+
diff --git a/...eographical-location-enrichment-guide.rst → ...er-and-reconciliation-interface-guide.rst b/...eographical-location-enrichment-guide.rst → ...er-and-reconciliation-interface-guide.rst
@@ -3,19 +3,19 @@
 .. Copyright (C) 2024 Nordix Foundation. All rights Reserved
 .. Copyright (C) 2024 OpenInfra Foundation Europe. All Rights Reserved
 
-Geographical enrichment guide
-#############################
+Discover and Reconciliation Interface Guide
+###########################################
 
-Geographical Enrichment Guide Overview
-======================================
+Discover and Reconciliation interface Guide Overview
+====================================================
 
-In this guide, we explore how to use the Geographical Location
-Enrichment API to enrich Topology & Inventory with geographical data.
+In this guide, we explore how to use the Discover and Reconciliation
+interface API to enrich Topology & Inventory with geographical data.
 
 Geographical enrichment
 =======================
 
-Geographical enrichment is the adding, modifying, and removing of
+Discover and Reconciliation 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:
@@ -230,6 +230,130 @@ The link provides a sample CloudEvents implementation in Java.
 CloudEvents SDKs also supports other languages. See
 `CloudEvents <https://cloudevents.io/>`__.
 
+Understanding Topology & Inventory ``id``
+=========================================
+
+When performing geographical enrichment of entities, the ``id`` value of the data, that is being enriched in
+Topology & Inventory, must match the ``id`` value for the entity or the relationship within the
+CloudEvent ``data`` element.
+
+There are two types of entities:
+
+- Entities that can be derived directly from CM. In the Topology & Inventory, these entities have only one
+  instance with the prefix **urn:3gpp:dn:** within the ``sourceIds`` list. Use this value as the entity ``id``
+  value within the CloudEvents ``data`` element.
+- Composite entities are entities that cannot be derived directly from CM. These entities have multiple instances
+  of **urn:3gpp:dn:** within the ``sourceIds`` list. The entity ``id`` value must be constructed from the list of
+  elements in the ``sourceIds`` list.
+
+The following is a sample CloudEvent for enriching an entity with geographical location information.
+
+.. image:: _static/dataCloudEvent.svg
+   :alt: Sample data for geographical enriching CloudEvent
+
+1. The list values for ``sourceIds`` is used to create the entity ``id``.
+2. The ``id`` is used to identify the correct entity.
+3. Geographical information enriches the entity.
+4. The relationship ``id`` is created from the aSide and bSide values which are the entity ``id``'s.
+
+To get the ``id`` values for composite entities, the advised method is to query the entities for matching
+``sourceIds`` elements, see :doc:`Topology & Inventory API <api-documentation>`. This
+can result in several matches where the same source entity participates in multiple topology entities.
+Otherwise, the entity ``id`` value and relationship ``id`` value are created as follows:
+
+How to create a composite entity ``id``
+---------------------------------------
+
+Composite entities are derived from multiple source domain elements.
+
+1. Get ``sourceIds`` of the composite entity.
+
+Example:
+
+::
+
+   "sourceIds": [
+      "urn:3gpp:dn:SubNetwork=Europe,SubNetwork=Ireland,MeContext=NR004,ManagedElement=me04,Equipment=1,AntennaUnitGroup=1,AntennaUnit=1",
+      "urn:3gpp:dn:SubNetwork=Europe,SubNetwork=Ireland,MeContext=NR004,ManagedElement=me04,Equipment=1,AntennaUnitGroup=1,AntennaUnit=1,AntennaSubunit=1",
+      "urn:3gpp:dn:SubNetwork=Europe,SubNetwork=Ireland,MeContext=NR004,ManagedElement=me04,Equipment=1,AntennaUnitGroup=1,AntennaNearUnit=1,RetSubUnit=12"
+   ]
+
+2. In the given order, combine each ``id`` with the prefix **urn:3gpp:dn** only. Separate the ``id``'s with ``;``.
+
+Format:
+
+::
+
+   <urn:3gpp:dn:Entity1>;<urn:3gpp:dn:Entity2>;...;<urn:3gpp:dn:EntityN>
+
+Example:
+
+::
+
+   urn:3gpp:dn:SubNetwork=Europe,SubNetwork=Ireland,MeContext=NR004,ManagedElement=me04,Equipment=1,AntennaUnitGroup=1,AntennaUnit=1;
+   urn:3gpp:dn:SubNetwork=Europe,SubNetwork=Ireland,MeContext=NR004,ManagedElement=me04,Equipment=1,AntennaUnitGroup=1,AntennaUnit=1,AntennaSubunit=1;
+   urn:3gpp:dn:SubNetwork=Europe,SubNetwork=Ireland,MeContext=NR004,ManagedElement=me04,Equipment=1,AntennaUnitGroup=1,AntennaNearUnit=1,RetSubUnit=12
+
+3. SHA-512 hash the combined ``id``'s.
+
+Example:
+
+::
+
+   1FEBF137533843657E9E9DBE60DBD86B045A057DB6D04B6A07AC15323F1906228E93CFA4A1DB37D50252B3AFE6AEC9860E2CEA4A77BB3A25C9EA45DEDA87E765
+
+4. Add the prefix **urn:o-ran:smo:teiv:sha512:** and the composite entity name = SHA-512 hashed ``id``'s.
+
+Format:
+
+::
+
+   urn:o-ran:smo:teiv:sha512:<CompositeEntityName>=<SHA-512 hashed IDs>
+
+
+Example:
+
+::
+
+   urn:o-ran:smo:teiv:sha512:AntennaModule=1FEBF137533843657E9E9DBE60DBD86B045A057DB6D04B6A07AC15323F1906228E93CFA4A1DB37D50252B3AFE6AEC9860E2CEA4A77BB3A25C9EA45DEDA87E765
+
+How to create a relationship ``id``
+-----------------------------------
+
+1. Combine the ``id`` of aSide and the ``id`` of bSide, split by the relationshipType, in the format:
+
+::
+
+   <aSideID>:<relationshipType>:<bSideID>
+
+Example:
+
+::
+
+   urn:3gpp:dn:SubNetwork=Europe,SubNetwork=Ireland,SubNetwork=ERBS01,ManagedElement=me01:
+   MANAGEDELEMENT_MANAGES_ENODEBFUNCTION:
+   urn:3gpp:dn:SubNetwork=Europe,SubNetwork=Ireland,SubNetwork=ERBS01,ManagedElement=me01,ENodeBFunction=1
+
+2. SHA-512 hash the previous format.
+
+Example:
+
+::
+
+   6D7E2A09E0F10C09548F86519084FDF1F021561FF07E116136D118E93568A0B4EA968A4B1E02B2CA4E057E00E582273DBE5A8CA1BF910FC65A9101117A0E9D7F
+
+3. Add the prefix **urn:o-ran:smo:teiv:sha512:** and the relationship type = the SHA-512 hashed as follows:
+
+::
+
+   urn:o-ran:smo:teiv:sha512:<RelationshipType>=<SHA-512 hash>
+
+Example:
+
+::
+
+   urn:o-ran:smo:teiv:sha512:MANAGEDELEMENT_MANAGES_ENODEBFUNCTION=6D7E2A09E0F10C09548F86519084FDF1F021561FF07E116136D118E93568A0B4EA968A4B1E02B2CA4E057E00E582273DBE5A8CA1BF910FC65A9101117A0E9D7F
+
 Troubleshooting
 ===============
 

diff --git a/.../geographical-location-enrichment-api.rst → ...discover-and-reconciliation-interface.rst b/.../geographical-location-enrichment-api.rst → ...discover-and-reconciliation-interface.rst
@@ -3,11 +3,10 @@
 .. Copyright (C) 2024 Nordix Foundation. All rights Reserved
 .. Copyright (C) 2024 OpenInfra Foundation Europe. All Rights Reserved
 
-Geographical Location Enrichment API 1.0.0beta1.0
-#################################################
+Discover and Reconciliation Interface
+#####################################
 
-Geographical Location Enrichment API to enrich topology with
-geographical data.
+Discover and Reconciliation Interface to enrich topology with data.
 
 Operations
 ==========

diff --git a/docs/index.rst b/docs/index.rst
@@ -18,9 +18,10 @@ to share and operate on a common view of the topology.
 
    ./developer-guide.rst
    ./query-api-examples.rst
+   ./classifiers-and-decorators.rst
    ./data-models-guide.rst
-   ./geographical-location-enrichment-guide.rst
-   ./geographical-location-enrichment-api.rst
+   ./discover-and-reconciliation-interface-guide.rst
+   ./discover-and-reconciliation-interface.rst
    ./supported-filter-options.rst
    ./api-documentation.rst
    ./pgsql-schema-generator-guide.rst