Merge "Query CM Handles RTD"

7 files changed, 299 insertions, 52 deletions

diff --git a/cps-ncmp-rest/docs/openapi/ncmp.yml b/cps-ncmp-rest/docs/openapi/ncmp.yml
index f394e85751..4266fc4152 100755
--- a/cps-ncmp-rest/docs/openapi/ncmp.yml
+++ b/cps-ncmp-rest/docs/openapi/ncmp.yml
@@ -273,7 +273,7 @@ fetchModuleDefinitionsByCmHandle:
 
 searchCmHandles:
   post:
-    description: Execute cm handle query search and return a list of cm handle details. Any number of conditions can be applied. To be included in the result a cm-handle must fulfill ALL the conditions. An empty collection will be returned in the case that the cm handle does not match a condition. For more on cm handle query search please refer to <a href="RTD page to be created in separate task">cm handle query search Read the Docs</a>.<br/>By supplying a CPS Path it is possible to query on any data related to the cm handle. For more on CPS Path please refer to <a href="https://docs.onap.org/projects/onap-cps/en/latest/cps-path.html">CPS Path Read the Docs</a>. The cm handle ancestor is automatically returned for this query.
+    description: Execute cm handle query search and return a list of cm handle details. Any number of conditions can be applied. To be included in the result a cm-handle must fulfill ALL the conditions. An empty collection will be returned in the case that the cm handle does not match a condition. For more on cm handle query search please refer to <a href="https://docs.onap.org/projects/onap-cps/en/latest/ncmp-cmhandle-querying.html">cm handle query search Read the Docs</a>.<br/>By supplying a CPS Path it is possible to query on any data related to the cm handle. For more on CPS Path please refer to <a href="https://docs.onap.org/projects/onap-cps/en/latest/cps-path.html">CPS Path Read the Docs</a>. The cm handle ancestor is automatically returned for this query.
     tags:
       - network-cm-proxy
     summary: Execute cm handle search using the available conditions
@@ -390,7 +390,7 @@ getCmHandleStateById:
 
 searchCmHandleIds:
   post:
-    description: Execute cm handle query search and return a list of cm handle ids. Any number of conditions can be applied. To be included in the result a cm-handle must fulfill ALL the conditions. An empty collection will be returned in the case that the cm handle does not match a condition. For more on cm handle query search please refer to <a href="RTD page to be created in separate task">cm handle query search Read the Docs</a>.<br/>By supplying a CPS Path it is possible to query on any data related to the cm handle. For more on CPS Path please refer to <a href="https://docs.onap.org/projects/onap-cps/en/latest/cps-path.html">CPS Path Read the Docs</a>. The cm handle ancestor is automatically returned for this query.
+    description: Execute cm handle query search and return a list of cm handle ids. Any number of conditions can be applied. To be included in the result a cm-handle must fulfill ALL the conditions. An empty collection will be returned in the case that the cm handle does not match a condition. For more on cm handle query search please refer to <a href="https://docs.onap.org/projects/onap-cps/en/latest/ncmp-cmhandle-querying.html">cm handle query search Read the Docs</a>.<br/>By supplying a CPS Path it is possible to query on any data related to the cm handle. For more on CPS Path please refer to <a href="https://docs.onap.org/projects/onap-cps/en/latest/cps-path.html">CPS Path Read the Docs</a>. The cm handle ancestor is automatically returned for this query.
     tags:
       - network-cm-proxy
     summary: Execute cm handle query upon a given set of query parameters
diff --git a/docs/api/yang/dmi-registry@2022-05-10.yang b/docs/api/yang/dmi-registry@2022-05-10.yang
new file mode 100644
index 0000000000..77517968c6
--- /dev/null
+++ b/docs/api/yang/dmi-registry@2022-05-10.yang
@@ -0,0 +1,123 @@
+module dmi-registry {
+
+  yang-version 1.1;
+
+  namespace "org:onap:cps:ncmp";
+
+  prefix dmi-reg;
+
+  contact "toine.siebelink@est.tech";
+
+  revision "2022-05-10" {
+    description
+    "Added DataSyncEnabled, SyncState with State, LastSyncTime, DataStoreSyncState with Operational and Running syncstate";
+  }
+
+  revision "2022-02-10" {
+    description
+    "Added State, LockReason, LockReasonDetails to aid with cmHandle sync and timestamp to aid with retry/timeout scenarios";
+  }
+
+  revision "2021-12-13" {
+    description
+    "Added new list of public additional properties for a Cm-Handle which are exposed to clients of the NCMP interface";
+  }
+
+  revision "2021-10-20" {
+    description
+    "Added dmi-data-service-name & dmi-model-service-name to allow separate DMI instances for each responsibility";
+  }
+
+  revision "2021-05-20" {
+    description
+    "Initial Version";
+  }
+
+  grouping LockReason {
+    leaf reason {
+      type string;
+    }
+    leaf details {
+      type string;
+    }
+  }
+
+  grouping SyncState {
+   leaf sync-state {
+     type string;
+   }
+   leaf last-sync-time {
+     type string;
+   }
+  }
+
+  grouping Datastores {
+    container operational {
+      uses SyncState;
+    }
+    container running {
+      uses SyncState;
+    }
+  }
+
+  container dmi-registry {
+    list cm-handles {
+      key "id";
+      leaf id {
+        type string;
+      }
+      leaf dmi-service-name {
+        type string;
+      }
+      leaf dmi-data-service-name {
+        type string;
+      }
+      leaf dmi-model-service-name {
+        type string;
+      }
+
+      list additional-properties {
+        key "name";
+        leaf name {
+          type string;
+        }
+        leaf value {
+          type string;
+        }
+      }
+
+      list public-properties {
+        key "name";
+        leaf name {
+          type string;
+        }
+        leaf value {
+          type string;
+        }
+      }
+
+      container state {
+        leaf cm-handle-state {
+          type string;
+        }
+
+        container lock-reason {
+          uses LockReason;
+        }
+
+        leaf last-update-time {
+          type string;
+        }
+
+        leaf data-sync-enabled {
+          type boolean;
+          default "false";
+        }
+
+        container datastores {
+          uses Datastores;
+        }
+      }
+    }
+  }
+}
\ No newline at end of file
diff --git a/docs/api/yang/dmiYangResource.yang b/docs/api/yang/dmiYangResource.yang
deleted file mode 100644
index 8e06a26948..0000000000
--- a/docs/api/yang/dmiYangResource.yang
+++ /dev/null
@@ -1,46 +0,0 @@
-module dmi-registry {
-
-  yang-version 1.1;
-
-  namespace \"org:onap:cps:ncmp\";
-
-  prefix dmi-reg;
-
-  organization \"Nordix Foundation\";
-
-  contact \"rahul.tyagi@est.tech\";
-
-  revision \"2021-05-20\" {
-    description
-    \"Initial Version\";
-  }
-
-  container dmi-registry {
-
-    list cm-handles {
-
-      key \"id\";
-
-      leaf id {
-        type string;
-      }
-
-      leaf dmi-service-name {
-        type string;
-      }
-
-      list additional-properties {
-
-        key \"name\";
-
-        leaf name {
-          type string;
-        }
-
-        leaf value {
-          type string;
-        }
-      }
-    }
-  }
-}
\ No newline at end of file
diff --git a/docs/cps-path.rst b/docs/cps-path.rst
index fba21f38c6..db754c5f8a 100644
--- a/docs/cps-path.rst
+++ b/docs/cps-path.rst
@@ -203,8 +203,6 @@ absolute-path
 **Limitations**
   - Absolute paths must start with the top element (data node) as per the model tree.
   - Each list reference must include a valid instance reference to the key for that list. Except when it is the last element.
-  - The Absolute path to list with integer key will not work. It needs to be surrounded with a single quote ([@code='1'])
-    as if it is a string. This will be fixed in `CPS-961 <https://jira.onap.org/browse/CPS-961>`_
 
 descendant-path
 ---------------
diff --git a/docs/design.rst b/docs/design.rst
index eb5f6b6e07..7a52255afd 100755
--- a/docs/design.rst
+++ b/docs/design.rst
@@ -1,6 +1,6 @@
 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
 .. http://creativecommons.org/licenses/by/4.0
-.. Copyright (C) 2021 Nordix Foundation
+.. Copyright (C) 2021-2022 Nordix Foundation
 
 .. DO NOT CHANGE THIS LABEL FOR RELEASE NOTES - EVEN THOUGH IT GIVES A WARNING
 .. _design:
@@ -71,3 +71,9 @@ CPS Path
 
 Several CPS APIs use the cps-path (or cpsPath in Java API) parameter.
 The CPS Path is described in detail in :doc:`cps-path`.
+
+NCMP CM Handle Querying
+=======================
+
+The CM Handle searches endpoints can be used to query for CM Handles or CM Handle IDs.
+This endpoint is described in detail in :doc:`ncmp-cmhandle-querying`.
\ No newline at end of file
diff --git a/docs/modeling.rst b/docs/modeling.rst
index b750c6d5b3..acc430aa1b 100644
--- a/docs/modeling.rst
+++ b/docs/modeling.rst
@@ -1,6 +1,7 @@
 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
 .. http://creativecommons.org/licenses/by/4.0
 .. Copyright (C) 2021 Pantheon.tech
+.. Modifications Copyright (C) 2021-2022 Nordix Foundation
 .. _modeling:
 
 .. toctree::
@@ -71,7 +72,9 @@ Data Model
 
 NCMP stores DMI-Plugin and CM Handle relations using a data model described as per this Yang module.
 
-:download:`DMI Yang Module <api/yang/dmiYangResource.yang>`
+:download:`DMI Yang Module <api/yang/dmi-registry@2022-05-10.yang>`
+
+Note: Although additional-properties are present in the model of the dmi-registry, these are considered private metadata and as such are not queryable.
 
 Basic Concepts
 --------------
@@ -91,3 +94,11 @@ Basic Concepts
     +--------------------------------+-------------------------------------+-------------------------+
     | Passthrough-running            | config-true                         | read-write              |
     +--------------------------------+-------------------------------------+-------------------------+
+
+Querying CM Handles
+
+- **CM Handle Searches Endpoints** are used to query CM Handles.
+.. toctree::
+   :maxdepth: 1
+
+   ncmp-cmhandle-querying.rst
\ No newline at end of file
diff --git a/docs/ncmp-cmhandle-querying.rst b/docs/ncmp-cmhandle-querying.rst
new file mode 100644
index 0000000000..5655d6c4a1
--- /dev/null
+++ b/docs/ncmp-cmhandle-querying.rst
@@ -0,0 +1,155 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. Copyright (C) 2022 Nordix Foundation
+
+.. DO NOT CHANGE THIS LABEL FOR RELEASE NOTES - EVEN THOUGH IT GIVES A WARNING
+.. _cmhandlequerying:
+
+
+CM Handle Query Endpoints
+#########################
+
+.. toctree::
+   :maxdepth: 1
+
+Introduction
+============
+
+For querying CM Handles we have two Post endpoints:
+
+- ncmp/v1/ch/searches Returns all CM Handles which match the query properties provided. Gives a JSON payload of the **details** of all matching CM Handles.
+
+- ncmp/v1/ch/id-searches Returns all CM Handles IDs which match the query properties provided. Gives a JSON payload of the **ids** of all matching CM Handles.
+
+/searches returns whole CM Handle object (data) whereas /id-searches returns only CM Handle IDs. Otherwise these endpoints are intended to be functionally identical so both can be queried with the same request body. If no matching CM Handles are found an empty array is returned.
+
+Request Body
+============
+
+Currently this endpoint allows three criteria to be query on:
+
+- *hasAllModules* returns CM Handles which have the module names provided.
+
+- *hasAllProperties* returns CM Handles which have the properties (key and value) provided.
+
+- *cmHandleWithCpsPath* returns CM Handles which match the CPS Path provided.
+
+Not all request body combinations have been validated and as such request bodies which do not conform to the structure as documented here can produce results in which all CM Handles are returned.
+
+Request Body example using all available query criteria. This query would return all CM Handles which have the specified modules my-module-(1-3), have the specified properties of Color yellow, Shape circle, Size small and are in a sync state of ADVISED:
+
+.. code-block:: json
+
+    {
+      "cmHandleQueryParameters": [
+        {
+          "conditionName": "hasAllModules",
+          "conditionParameters": [
+            {
+              "moduleName": "my-module-1"
+            },
+            {
+              "moduleName": "my-module-2"
+            },
+            {
+              "moduleName": "my-module-3"
+            }
+          ]
+        },
+        {
+          "conditionName": "hasAllProperties",
+          "conditionParameters": [
+            {
+              "Color": "yellow"
+            },
+            {
+              "Shape": "circle"
+            },
+            {
+              "Size": "small"
+            }
+          ]
+        },
+        {
+          "conditionName": "cmHandleWithCpsPath",
+          "conditionParameters": [
+            {
+              "cpsPath": "//state[@cm-handle-state='ADVISED']"
+            }
+          ]
+        }
+      ]
+    }
+
+
+Has all Modules
+---------------
+
+With the *hasAllModules* condition, we can provide a list of module names. The CM Handles returned will have these module names. The parameter names must be as below with the key of each of the module names being "moduleName" where "my-module-X" is to be replaced with the name of the module to query with. The returned CM Handle must have all supplied modules. For the example request, a CM Handle will be returned if it has "my-module-1", "my-module-2" and "my-module-3".
+
+.. code-block:: json
+
+    {
+      "cmHandleQueryParameters": [
+        {
+          "conditionName": "hasAllModules",
+          "conditionParameters": [
+            {
+              "moduleName": "my-module-1"
+            },
+            {
+              "moduleName": "my-module-2"
+            },
+            {
+              "moduleName": "my-module-3"
+            }
+          ]
+        }
+      ]
+    }
+
+Has all Properties
+------------------
+
+With the *hasAllProperties* condition, we can provide a list of property keys and values. The CM Handles returned will have these properties. The parameter names must be as below with key and value for each property. The returned CM Handle must have all supplied properties. For the example request, a CM Handle will be returned if it has properties where there is a key of "Color" with value "yellow", a key of "Shape" with value "circle" and a key of "Size" with value "small".
+
+.. code-block:: json
+
+    {
+      "cmHandleQueryParameters": [
+        {
+          "conditionName": "hasAllProperties",
+          "conditionParameters": [
+            {
+              "Color": "yellow"
+            },
+            {
+              "Shape": "circle"
+            },
+            {
+              "Size": "small"
+            }
+          ]
+        }
+      ]
+    }
+
+CM Handle with CPS Path
+-----------------------
+
+The *cmHandleWithCpsPath* condition allows any data of the CM Handle to be queried as long as it is accessible by CPS path. CPS path is described in detail in :doc:`cps-path`. For this endpoint, the ancestor of CM Handles is appended automatically so that a CM Handle is always returned. For example ``//state[@cm-handle-state='LOCKED']`` will become ``//state[@cm-handle-state='LOCKED']/ancestor::cm-handles``. The yang model for the dmi-registry can be found in :doc:`modeling` under the NCMP Modeling Section. Please note that although CM Handle additional-properties are shown in the dmi-registry yang model, these are considered private properties and cannot be used to query CM Handles. Any attempt to use the additional-properties to query will return an empty array.
+
+.. code-block:: json
+
+    {
+      "cmHandleQueryParameters": [
+        {
+          "conditionName": "cmHandleWithCpsPath",
+          "conditionParameters": [
+            {
+              "cpsPath": "//state[@cm-handle-state='LOCKED']"
+            }
+          ]
+        }
+      ]
+    }
\ No newline at end of file