From b11cafecc2a038449254be52abfb67ec6c063fe1 Mon Sep 17 00:00:00 2001 From: JvD_Ericsson Date: Tue, 10 Sep 2024 15:41:19 +0100 Subject: [PATCH] TEIV: Update docs Issue-ID: SMO-155 Change-Id: Ic2e468d54a25eeeb5c664d547c1fc02d32adde6c Signed-off-by: JvD_Ericsson --- docs/_static/dataCloudEvent.svg | 1 + docs/classifiers-and-decorators.rst | 111 +++++++ docs/developer-guide.rst | 19 +- ...iscover-and-reconciliation-interface-guide.rst} | 138 ++++++++- ...t => discover-and-reconciliation-interface.rst} | 7 +- docs/index.rst | 5 +- docs/pgsql-schema-generator-guide.rst | 71 +---- docs/supported-filter-options.rst | 323 ++++++++++++++++++--- 8 files changed, 553 insertions(+), 122 deletions(-) create mode 100644 docs/_static/dataCloudEvent.svg create mode 100644 docs/classifiers-and-decorators.rst rename docs/{geographical-location-enrichment-guide.rst => discover-and-reconciliation-interface-guide.rst} (62%) rename docs/{geographical-location-enrichment-api.rst => discover-and-reconciliation-interface.rst} (99%) diff --git a/docs/_static/dataCloudEvent.svg b/docs/_static/dataCloudEvent.svg new file mode 100644 index 0000000..5a3f029 --- /dev/null +++ b/docs/_static/dataCloudEvent.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/classifiers-and-decorators.rst b/docs/classifiers-and-decorators.rst new file mode 100644 index 0000000..afda7c4 --- /dev/null +++ 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 `. +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 + `. 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 + `. + +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 index 1ca19f4..e1fd098 100644 --- 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 ` 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/docs/geographical-location-enrichment-guide.rst b/docs/discover-and-reconciliation-interface-guide.rst similarity index 62% rename from docs/geographical-location-enrichment-guide.rst rename to docs/discover-and-reconciliation-interface-guide.rst index 64edd13..75c3fec 100644 --- a/docs/geographical-location-enrichment-guide.rst +++ b/docs/discover-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 `__. +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 `. 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: + +:: + + ;;...; + +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:= + + +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: + +:: + + :: + +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:= + +Example: + +:: + + urn:o-ran:smo:teiv:sha512:MANAGEDELEMENT_MANAGES_ENODEBFUNCTION=6D7E2A09E0F10C09548F86519084FDF1F021561FF07E116136D118E93568A0B4EA968A4B1E02B2CA4E057E00E582273DBE5A8CA1BF910FC65A9101117A0E9D7F + Troubleshooting =============== diff --git a/docs/geographical-location-enrichment-api.rst b/docs/discover-and-reconciliation-interface.rst similarity index 99% rename from docs/geographical-location-enrichment-api.rst rename to docs/discover-and-reconciliation-interface.rst index 92fc4ca..b102773 100644 --- a/docs/geographical-location-enrichment-api.rst +++ b/docs/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 index eaa9e66..9234018 100644 --- 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 diff --git a/docs/pgsql-schema-generator-guide.rst b/docs/pgsql-schema-generator-guide.rst index d833874..9d79643 100644 --- a/docs/pgsql-schema-generator-guide.rst +++ b/docs/pgsql-schema-generator-guide.rst @@ -388,60 +388,15 @@ The user must provide a unique module name, to avoid collision of multiple users 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 -""""""""""" - -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-block:: 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-block:: 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" - ] - } +Classifiers Details +""""""""""""""""""" + +:ref:`
` + +Decorators Details +"""""""""""""""""" + +:ref:`Details for decorators here ` The SQL entries for consumer data include - **module_reference:** For the consumer module reference related module names from provided classifiers or decorators retrieved from the model service are extracted and stored which will be used for execution to module_reference table. @@ -499,12 +454,10 @@ The SQL entries for consumer data include | | ON DELETE CASCADE | | | +--------------------------------------------------+------------------+-----------------------------------+ -How to use classifiers and decorators -""""""""""""""""""""""""""""""""""""" +Information on how to use classifiers and decorators +"""""""""""""""""""""""""""""""""""""""""""""""""""" -1. Create a schema with the /schemas endpoint using Yang Module. After a 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 queries. +:ref:`Information on how to use classifiers and decorators here ` Skeleton Data and Model SQL Files ================================= diff --git a/docs/supported-filter-options.rst b/docs/supported-filter-options.rst index 8d75a27..081070d 100644 --- a/docs/supported-filter-options.rst +++ b/docs/supported-filter-options.rst @@ -76,12 +76,12 @@ be retrieved and filtered using the /attributes. | | *AND* or *OR*". | | | | | | +------------------------------------------+--------+----------------+--------------+------------------------+------------------------+ | | To return the ids for all instances of | RAN | GNBDUFunction | | /attributes | | Unique set of ids of | -| | the entityTypeName used in the query, | | | | [@gNBId Length=3] | | GNBDUFunctions, | -| | that satisfies one of | | | | | | | where the | -| | the conditions in the *scopeFilter* | | | | | | gNBIdLength equals 3 | -| | parameter. A condition is a complete | | | | /sourceIds | | or the sourceIds | -| | unit of *scopeFilter* | | | | [contains (@item, | | contains an item | -| | represent OR. | | | | 'SubNetwork=Ireland')] | | with | +| | the entityTypeName used in the query, | | | | [@gNBId Length=3] | | | GNBDUFunctions, | +| | that satisfies one of | | | | | | where the | +| | the conditions in the *scopeFilter* | | | | /sourceIds | | gNBIdLength equals 3 | +| | parameter. A condition is a complete | | | | [contains (@item, | | or the sourceIds | +| | unit of *scopeFilter* | | | | 'SubNetwork=Ireland')] | | contains an item | +| | represent OR. | | | | | | with | | | parameter surrounded by square | | | | | | "SubNetwork=Ireland" | | | brackets. Note: Multiple conditions | | | | | | | | can be given in the scopeFilter | | | | | | @@ -101,29 +101,24 @@ The *entityTypeName* is used as the root of the queries. +------------------------------------------+-------------+----------------+--------------+----------------------------+--------------------------------------------------+ | Use case | domainName | entityTypeName | targetFilter | scopeFilter | Query result | +==========================================+=============+================+==============+============================+==================================================+ -| | To return the ids for all instances of | OAM_TO_RAN | ENodeBFunction | | /managed-by-managedElement | | All ENodeBFunction entities that are managed | +| | To return the ids for all instances of | REL_OAM_RAN | GNBDUFunction | | /managed-by-managedElement | | All GNBDUFunction entities that are managed | | | an entityTypeName related by an | | | | | | by any Managed Element. | | | association. | | | | | | +------------------------------------------+-------------+----------------+--------------+----------------------------+--------------------------------------------------+ -| | To return the ids for all instances of | OAM_TO_RAN | ENodeBFunction | | /managed-by-managedElement | | All ENodeBFunction entities that are managed | +| | To return the ids for all instances of | REL_OAM_RAN | GNBDUFunction | | /managed-by-managedElement | | All GNBDUFunction entities that are managed | | | an entityTypeName related by an | | | | [@id = 'urn\:3gpp:dn: | | by the Managed Element | | | association to another entity | | | | ManagedElement=1'] | | *urn\:3gpp:dn: ManagedElement=1*. | | | specified by its *id*. | | | | | | +------------------------------------------+-------------+----------------+--------------+----------------------------+--------------------------------------------------+ -| | To return the attributes for all | OAM_TO_RAN | ENodeBFunction | /attributes | /attributes [@enbId=1]; | | All EnodeBFunction entities with enbId as *1* | +| | To return the attributes for all | REL_OAM_RAN | GNBDUFunction | /attributes | /attributes [@enbId=1]; | | All GNBDUFunction entities with enbId as *1* | | | instances of an entityTypeName | | | | | | managed by the Managed Element | | | related by one or more associations | | | | /managed-by-managedElement | | *urn\:3gpp:dn: ManagedElement=1* or | -| | to other entities specified by their | | | | [@id='urn\:3gpp:dn: | | *urn\:3gpp:dn: ManagedElement=2*, | -| | *id*. | | | | ManagedElement=1'] | | | and provides EuTranCell | -| | | | | | | *urn\:3gpp:dn: ManagedElement=1, EUtranCell=2* | -| | | | | /managed-by-managedElement | | -| | | | | [@id='urn\:3gpp:dn: | | -| | | | | ManagedElement=2'] ; | | +| | to other entities specified by their | | | | [@id='urn\:3gpp:dn: | | *urn\:3gpp:dn: ManagedElement=2* | +| | *id*. | | | | ManagedElement=1'] | | | | | | | | | | -| | | | | /provided-euTranCell | | +| | | | | /managed-by-managedElement | | | | | | | [@id='urn\:3gpp:dn: | | -| | | | | ManagedElement=1, | | -| | | | | EUtranCell=2'] | | +| | | | | ManagedElement=2'] | | +------------------------------------------+-------------+----------------+--------------+----------------------------+--------------------------------------------------+ @@ -135,25 +130,25 @@ Querying entities for relationships The *entityTypeName* is used as the root of the queries. -+------------------------------------------+--------+----------------+-------------------+--------+----------------------------+-----------------------------------------------------+ -| Use case | domain | entityTypeName | entityId | target | scopeFilter | Query result | -| | | | | | | | -| | Name | | | Filter | | | -+==========================================+========+================+===================+========+============================+=====================================================+ -| | To return the relationships for a | RAN | GNBDUFunction | urn\:3gpp:dn: | | | | All relations for the GNBDUFunction with id | -| | given entity specified by its id. | | | ManagedElement=1, | | | | *urn\:3gpp:dn: ManagedElement=1, GNBDUFunction=1* | -| | | | GNBDUFunction=1 | | | | -+------------------------------------------+--------+----------------+-------------------+--------+----------------------------+-----------------------------------------------------+ -| | To return specific relationships for a | RAN | GNBDUFunction | urn\:3gpp:dn: | | /MANAGEDELEMENT | | All *MANAGEDELEMENT _MANAGES _GNBDUFUNCTION* | -| | given entity specified by its id. | | | ManagedElement=1, | | _MANAGES | | relations for the GNBDUFunction with id | -| | | | GNBDUFunction=1 | | _GNBDUFUNCTION | | *urn\:3gpp:dn: ManagedElement=1, GNBDUFunction=1* | -+------------------------------------------+--------+----------------+-------------------+--------+----------------------------+-----------------------------------------------------+ -| | To return specific relationships for | RAN | GNBDUFunction | urn\:3gpp:dn: | | /managed-by-managedElement | | All *MANAGEDELEMENT _MANAGES _GNBDUFUNCTION* | -| | an entity specified by its id to | | | ManagedElement=1, | | [@id = 'urn\:3gpp:dn: | | relations for the GNBDUFunction with id | -| | another entity using its id and | | | GNBDUFunction=1 | | ManagedElement=1'] | | *urn\:3gpp:dn: ManagedElement=1, GNBDUFunction=1* | -| | association. | | | | | | | where the managed element is | -| | | | | | | | *urn\:3gpp:dn: ManagedElement=1*. | -+------------------------------------------+--------+----------------+-------------------+--------+----------------------------+-----------------------------------------------------+ ++------------------------------------------+-------------+----------------+-------------------+-----------------+----------------------------+-----------------------------------------------------+ +| Use case | domainName | entityTypeName | entityId | targetFilter | scopeFilter | Query result | +| | | | | | | | +| | | | | | | | ++==========================================+=============+================+===================+=================+============================+=====================================================+ +| | To return the relationships for a | RAN | GNBDUFunction | urn\:3gpp:dn: | | | | All relations for the GNBDUFunction with id | +| | given entity specified by its id. | | | ManagedElement=1, | | | | *urn\:3gpp:dn: ManagedElement=1, GNBDUFunction=1* | +| | | | GNBDUFunction=1 | | | | ++------------------------------------------+-------------+----------------+-------------------+-----------------+----------------------------+-----------------------------------------------------+ +| | To return specific relationships for a | REL_OAM_RAN | GNBDUFunction | urn\:3gpp:dn: | /MANAGEDELEMENT | | | All *MANAGEDELEMENT _MANAGES _GNBDUFUNCTION* | +| | given entity specified by its id. | | | ManagedElement=1, | _MANAGES | | | relations for the GNBDUFunction with id | +| | | | GNBDUFunction=1 | _GNBDUFUNCTION | | | *urn\:3gpp:dn: ManagedElement=1, GNBDUFunction=1* | ++------------------------------------------+-------------+----------------+-------------------+-----------------+----------------------------+-----------------------------------------------------+ +| | To return specific relationships for | REL_OAM_RAN | GNBDUFunction | urn\:3gpp:dn: | | /managed-by-managedElement | | All *MANAGEDELEMENT _MANAGES _GNBDUFUNCTION* | +| | an entity specified by its id to | | | ManagedElement=1, | | [@id = 'urn\:3gpp:dn: | | relations for the GNBDUFunction with id | +| | another entity using its id and | | | GNBDUFunction=1 | | ManagedElement=1'] | | *urn\:3gpp:dn: ManagedElement=1, GNBDUFunction=1* | +| | association. | | | | | | | where the managed element is | +| | | | | | | | *urn\:3gpp:dn: ManagedElement=1*. | ++------------------------------------------+-------------+----------------+-------------------+-----------------+----------------------------+-----------------------------------------------------+ Querying on relationships ------------------------- @@ -168,11 +163,11 @@ Here, the *relationshipTypeName* is used as the root of the queries. | | | Type Name | | | | | | | | Filter | | | +==========================================+=============+=================+========+============================+=================================================+ -| | To return all relationships for a | OAM_TO_RAN | MANAGEDELEMENT | | | | All MANAGEDELEMENT_MANAGES_ENODEBFUNCTION | +| | To return all relationships for a | REL_OAM_RAN | MANAGEDELEMENT | | | | All MANAGEDELEMENT_MANAGES_ENODEBFUNCTION | | | specified relationship | | _MANAGES | | | | relationships | | | | _ENODEBFUNCTION | | | | +------------------------------------------+-------------+-----------------+--------+----------------------------+-------------------------------------------------+ -| | To return all relationships for a | OAM_TO_RAN | MANAGEDELEMENT | | /managed-by-managedElement | | All MANAGEDELEMENT_MANAGES_ENODEBFUNCTION | +| | To return all relationships for a | REL_OAM_RAN | MANAGEDELEMENT | | /managed-by-managedElement | | All MANAGEDELEMENT_MANAGES_ENODEBFUNCTION | | | specified relationship type with a | | _MANAGES | | [@id='urn\:3gpp:dn: | | relationships having an association | | | specified association to an entity. | | _ENODEBFUNCTION | | ManagedElement=1'] | | *managed-by-managedElement* to ManagedElement | | | | | | | | *urn\:3gpp:dn: ManagedElement=1*. | @@ -184,8 +179,254 @@ Here, the *relationshipTypeName* is used as the root of the queries. **/domains/{domainName}/relationship-types/{relationshipTypeName}/relationships/{relationshipId}** **Example:** Get the *MANAGEDELEMENT_MANAGES_ENODEBFUNCTION* -relationship with id *rel1* in the *OAM_TO_RAN* domain: +relationship with id *rel1* in the *REL_OAM_RAN* domain: + +:: + + GET https:///topology-inventory//domains/REL_OAM_RAN/relationship-types/MANAGEDELEMENT_MANAGES_ENODEBFUNCTION/relationships/rel1 + +Querying on classifiers and decorators +************************************** + +This functionality is supported by the following endpoints + +:: + + **/domains/{domainName}/entities** + ++-------------------------------------------+--------+--------+-----------------------+------------------------------------------+ +| Use case | domain | target | scopeFilter | Query result | +| | | | | | +| | Name | Filter | | | ++===========================================+========+========+=======================+==========================================+ +| | Return all related entity IDs that are | RAN | | /classifiers[@item = | | All the entity IDs that are classified | +| | exactly matched with the specified | | | 'gnbdu-function-model | | with "gnbdu-function-model:Indoor" | +| | classifier with given domain name. | | | :Indoor'] | | in RAN domain. | ++-------------------------------------------+--------+--------+-----------------------+------------------------------------------+ +| | Return all related entity IDs that are | RAN | | /classifiers[contains | | All the entity IDs that are partially | +| | partially matched for the given | | | (@item, 'Ind')] | | matched with "Ind" in RAN domain. | +| | classifier with given domain name. | | | | | ++-------------------------------------------+--------+--------+-----------------------+------------------------------------------+ +| | Return all related entity IDs that are | RAN | | /decorators[ | | All the entity IDs that are exactly | +| | exactly matched with the key-value pair | | | @gnbdu-function-model | | matched with | +| | that specified decorators | | | :textdata = | | "gnbdu-function-model:textdata = | +| | with given domain name. | | | 'Stockholm'] | | 'Stockholm'" in RAN domain. | ++-------------------------------------------+--------+--------+-----------------------+------------------------------------------+ +| | Return all related entity IDs that are | RAN | | /decorators[contains( | | All the entity IDs that are exactly | +| | exactly matched with key parameter | | | @gnbdu-function-model | | matched with | +| | where the value of the decorator is | | | :textdata, "")] | | "gnbdu-function-model:textdata as key | +| | unknown with given domain name. | | | | | of the decorator in RAN domain. | ++-------------------------------------------+--------+--------+-----------------------+------------------------------------------+ + +**Example:** Get the decorators *gnbdu-function-model:textdata = 'Stockholm' in the RAN domain* + +:: + + GET https:///topology-inventory//domains/REL_OAM_RAN/entities?scopeFilter=/decorators[@o-ran-smo-teiv-ran:textdata = 'Stockholm'] + +**Result** + +.. code:: json + + { + "items": [ + { + "o-ran-smo-teiv-ran:GNBDUFunction": [ + { + "id": "urn:3gpp:dn:SubNetwork=Europe,SubNetwork=Hungary,MeContext=1,ManagedElement=13,GNBDUFunction=13" + } + ] + }, + { + "o-ran-smo-teiv-ran:GNBDUFunction": [ + { + "id": "urn:3gpp:dn:SubNetwork=Europe,SubNetwork=Hungary,MeContext=1,ManagedElement=14,GNBDUFunction=14" + } + ] + }, + { + "o-ran-smo-teiv-ran:GNBDUFunction": [ + { + "id": "urn:3gpp:dn:SubNetwork=Europe,SubNetwork=Hungary,MeContext=1,ManagedElement=16,GNBDUFunction=16" + } + ] + } + ], + "self": { + "href": "/domains/RAN/entities?offset=0&limit=500&scopeFilter=/decorators[@o-ran-smo-teiv-ran:textdata = 'Stockholm']" + }, + "first": { + "href": "/domains/RAN/entities?offset=0&limit=500&scopeFilter=/decorators[@o-ran-smo-teiv-ran:textdata = 'Stockholm']" + }, + "prev": { + "href": "/domains/RAN/entities?offset=0&limit=500&scopeFilter=/decorators[@o-ran-smo-teiv-ran:textdata = 'Stockholm']" + }, + "next": { + "href": "/domains/RAN/entities?offset=0&limit=500&scopeFilter=/decorators[@o-ran-smo-teiv-ran:textdata = 'Stockholm']" + }, + "last": { + "href": "/domains/RAN/entities?offset=0&limit=500&scopeFilter=/decorators[@o-ran-smo-teiv-ran:textdata = 'Stockholm']" + }, + "totalCount": 3 + } + +:: + + **/domains/{domainName}/entity-types/{entityName}/entities** + ++-------------------------------------+--------------+--------------+---------------------------+--------------------------------------------------------+---------------------------------------------------+ +| Use case | entityName | relationship | targetFilter | scopeFilter | Query result | +| | | | | | | +| | | TypeName | | | | ++=====================================+==============+==============+===========================+========================================================+===================================================+ +| | Return all related entity IDs and | NRCellDU | | /classifiers | | All NRCellDU IDs and classifiers. | +| | classifiers. | | | | | | ++-------------------------------------+--------------+--------------+---------------------------+--------------------------------------------------------+---------------------------------------------------+ +| | Return all related entity IDs and | NRCellDU | | /decorators | | All NRCellDU IDs and decorators. | +| | decorators. | | | | | | ++-------------------------------------+--------------+--------------+---------------------------+--------------------------------------------------------+---------------------------------------------------+ +| | Return all related entity IDs | NRCellDU | | | | /classifiers[@item = 'gnbdu-function-model:Indoor']; | | All NRCellDU IDs where key of the decorator is | +| | that are an exact match for the | | | | | /decorators[@gnbdu-function-model:textdata = | | "gnbdu-function-model:textdata" and the value | +| | given classifiers and decorators. | | | | | 'Stockholm'] | | of the decorator is 'Stockholm' and classifiers | +| | | | | | | exactly contain "gnbdu-function-model:Indoor". | ++-------------------------------------+--------------+--------------+---------------------------+--------------------------------------------------------+---------------------------------------------------+ +| | Return all related entity IDs and | NRCellDU | | /classifiers | /classifiers[contains(@item, 'Ind')] | | All NRCellDU IDs and classifiers partially | +| | classifiers that are partially | | | | | | contain the text "Ind". | +| | matched for the given classifier. | | | | | | ++-------------------------------------+--------------+--------------+---------------------------+--------------------------------------------------------+---------------------------------------------------+ +| | Return all related entity IDs and | NRCellDU | | /decorators | | /decorators[contains(@gnbdu-function-model:textdata, | | All NRCellDU IDs and where key of the decorator | +| | decorators where the key is an | | | | | 'Stoc')] | | is "gnbdu-function-model:textdata" and the | +| | exact match and the value is a | | | | | | value of the decorator partially contains | +| | partial match. | | | | | | 'Stoc' | ++-------------------------------------+--------------+--------------+---------------------------+--------------------------------------------------------+---------------------------------------------------+ +| | Return all related entity IDs and | NRCellDU | | /classifiers; /decorators | | /classifiers[contains(@item, 'Ind')]; | | All NRCellDU IDs and decorators where the key | +| | decorators where the key is an | | | | | /decorators[contains(@gnbdu-function-model:textdata, | | of the decorator is | +| | exact match and the value is a | | | | | 'Stoc')] | | "gnbdu-function-model:textdata", the value of | +| | partial match. | | | | | | the decorator partially contains 'Stoc', and | +| | | | | | | the classifiers partially contain "Ind". | ++-------------------------------------+--------------+--------------+---------------------------+--------------------------------------------------------+---------------------------------------------------+ + +**Example:** Get the entities and classifiers where the classifier contains the text *Indoor* + +:: + + GET https:///topology-inventory//domains/RAN/entity-types/NRCellDU/entities?targetFilter=/classifiers&scopeFilter=/classifiers[contains(@item, 'Rural')] + +**Result** + +.. code:: json + + { + "items": [ + { + "o-ran-smo-teiv-ran:NRCellDU": [ + { + "classifiers": [ + "o-ran-smo-teiv-ran:Rural" + ], + "id": "urn:3gpp:dn:SubNetwork=Europe,SubNetwork=Hungary,MeContext=1,ManagedElement=19,GNBDUFunction=19,NRCellDU=93" + } + ] + } + ], + "self": { + "href": "/domains/RAN/entity-types/NRCellDU/entities?offset=0&limit=500&targetFilter=/classifiers&scopeFilter=/classifiers[contains(@item, 'Rural')]" + }, + "first": { + "href": "/domains/RAN/entity-types/NRCellDU/entities?offset=0&limit=500&targetFilter=/classifiers&scopeFilter=/classifiers[contains(@item, 'Rural')]" + }, + "prev": { + "href": "/domains/RAN/entity-types/NRCellDU/entities?offset=0&limit=500&targetFilter=/classifiers&scopeFilter=/classifiers[contains(@item, 'Rural')]" + }, + "next": { + "href": "/domains/RAN/entity-types/NRCellDU/entities?offset=0&limit=500&targetFilter=/classifiers&scopeFilter=/classifiers[contains(@item, 'Rural')]" + }, + "last": { + "href": "/domains/RAN/entity-types/NRCellDU/entities?offset=0&limit=500&targetFilter=/classifiers&scopeFilter=/classifiers[contains(@item, 'Rural')]" + }, + "totalCount": 1 + } :: - GET https:///topology-inventory//domains/OAM_TO_RAN/relationship-types/MANAGEDELEMENT_MANAGES_ENODEBFUNCTION/relationships/rel1 + **/domains/{domainName}/relationship-types/{relationshipTypeName}/relationships** + ++-------------------------------+--------+-------------------------+--------------------+-----------------------------+ +| Use case | entity | relationshipTypeName | targetFilter | scopeFilter | +| | | | | | +| | Name | | | | ++===============================+========+=========================+====================+=============================+ +| | Return all related | | MANAGEDELEMENT _MANAGES | /classifiers | | +| | relationship IDs and | | _ENODEBFUNCTION | | | +| | classifiers. | | | | | ++-------------------------------+--------+-------------------------+--------------------+-----------------------------+ +| | Return all related | | MANAGEDELEMENT _MANAGES | /decorators | | +| | relationship IDs and | | _ENODEBFUNCTION | | | +| | decorators. | | | | | ++-------------------------------+--------+-------------------------+--------------------+-----------------------------+ +| | Return related relationship | | MANAGEDELEMENT _MANAGES | | /classifiers[@item = | +| | IDs that match the | | _ENODEBFUNCTION | | 'gnbdu-function-model | +| | classifier and decorator. | | | | :Indoor']; | +| | | | | | +| | | | | /decorators[@gnbdu-function | +| | | | | -model:textdata = | +| | | | | 'Stockholm'] | ++-------------------------------+--------+-------------------------+--------------------+-----------------------------+ +| | Return related relationship | | MANAGEDELEMENT _MANAGES | /classifiers | /classifiers[contains | +| | IDs and classifiers that | | _ENODEBFUNCTION | | (@item, 'Ind')] | +| | are partially matched | | | | | +| | for the classifier. | | | | | ++-------------------------------+--------+-------------------------+--------------------+-----------------------------+ +| | Return related relationship | | MANAGEDELEMENT _MANAGES | /decorators | /decorators[contains | +| | IDs and decorators where | | _ENODEBFUNCTION | | (@gnbdu-function-model: | +| | the key matches exactly and | | | | textdata, 'Stock')] | +| | the value matches | | | | | +| | partially. | | | | | ++-------------------------------+--------+-------------------------+--------------------+-----------------------------+ +| | Return related relationship | | MANAGEDELEMENT _MANAGES | | /classifiers | /classifiers[contains | +| | IDs, decorators, and | | _ENODEBFUNCTION | | /decorators | (@item, 'Ind')]; | +| | classifiers where decorator | | | | /decorators[contains | +| | key is exact and value | | | | (@gnbdu-function-model: | +| | partially matches, and | | | | textdata, 'Stock')] | +| | classifiers partially match | | | | | +| | the parameters. | | | | | ++-------------------------------+--------+-------------------------+--------------------+-----------------------------+ + + +**Result** + +.. code:: json + + { + "items": [ + { + "o-ran-smo-teiv-rel-oam-ran:MANAGEDELEMENT_MANAGES_GNBDUFUNCTION": [ + { + "bSide": "urn:3gpp:dn:SubNetwork=Europe,SubNetwork=Hungary,MeContext=1,ManagedElement=10,GNBDUFunction=10", + "aSide": "urn:3gpp:dn:SubNetwork=Europe,SubNetwork=Hungary,MeContext=1,ManagedElement=10", + "classifiers": [ + "o-ran-smo-teiv-ran:Rural", + "o-ran-smo-teiv-ran:Weekend" + ], + "id": "urn:o-ran:smo:teiv:sha512:MANAGEDELEMENT_MANAGES_GNBDUFUNCTION=661A89AD3C2702233CD9E96E97E738C05C35EC5FDF32DC78D149B773726350067315B72448D004C938BCD0263F0C4BCCC8A5F9CDD145B9B740983D1523664328" + } + ] + } + ], + "self": { + "href": "/domains/REL_OAM_RAN/relationship-types/MANAGEDELEMENT_MANAGES_GNBDUFUNCTION/relationships?offset=0&limit=500&scopeFilter=/classifiers[@item = 'o-ran-smo-teiv-ran:Rural']&targetFilter=/classifiers" + }, + "first": { + "href": "/domains/REL_OAM_RAN/relationship-types/MANAGEDELEMENT_MANAGES_GNBDUFUNCTION/relationships?offset=0&limit=500&scopeFilter=/classifiers[@item = 'o-ran-smo-teiv-ran:Rural']&targetFilter=/classifiers" + }, + "prev": { + "href": "/domains/REL_OAM_RAN/relationship-types/MANAGEDELEMENT_MANAGES_GNBDUFUNCTION/relationships?offset=0&limit=500&scopeFilter=/classifiers[@item = 'o-ran-smo-teiv-ran:Rural']&targetFilter=/classifiers" + }, + "next": { + "href": "/domains/REL_OAM_RAN/relationship-types/MANAGEDELEMENT_MANAGES_GNBDUFUNCTION/relationships?offset=0&limit=500&scopeFilter=/classifiers[@item = 'o-ran-smo-teiv-ran:Rural']&targetFilter=/classifiers" + }, + "last": { + "href": "/domains/REL_OAM_RAN/relationship-types/MANAGEDELEMENT_MANAGES_GNBDUFUNCTION/relationships?offset=0&limit=500&scopeFilter=/classifiers[@item = 'o-ran-smo-teiv-ran:Rural']&targetFilter=/classifiers" + }, + "totalCount": 1 + } \ No newline at end of file -- 2.16.6