diff options
| -rw-r--r-- | docs/cm-handle-lcm-events.rst | 117 | ||||
| -rw-r--r-- | docs/cps-events.rst | 157 | ||||
| -rw-r--r-- | docs/cps-ncmp-message-status-codes.rst | 41 | ||||
| -rw-r--r-- | docs/data-operation-events.rst | 64 | ||||
| -rw-r--r-- | docs/modeling.rst | 15 | ||||
| -rw-r--r-- | docs/ncmp-async-events.rst | 54 | ||||
| -rw-r--r-- | docs/ncmp-data-operation.rst | 148 | ||||
| -rw-r--r-- | docs/schemas/data-operation-event-schema-1.0.0.json | 69 |
8 files changed, 514 insertions, 151 deletions
diff --git a/docs/cm-handle-lcm-events.rst b/docs/cm-handle-lcm-events.rst new file mode 100644 index 0000000000..8446834c31 --- /dev/null +++ b/docs/cm-handle-lcm-events.rst @@ -0,0 +1,117 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 +.. Copyright (C) 2023 Nordix Foundation + +.. DO NOT CHANGE THIS LABEL FOR RELEASE NOTES - EVEN THOUGH IT GIVES A WARNING +.. _cmHandleLcmEvents: + + +CM Handle Lifecycle Management (LCM) Events +########################################### + +.. toctree:: + :maxdepth: 1 + +Introduction +============ + +LCM events for CM Handles are published when a CM Handle is created, deleted or another change in the cm handle state occurs. + + **3 possible event types:** + + * Create + * Update + * Delete + +CM Handle LCM Event Schema +--------------------------- +The current published LCM event is based on the following schema: + +:download:`Life cycle management event schema <schemas/lcm-event-schema-v1.json>` + +CM Handle LCM Event structure +----------------------------- + +Events header +^^^^^^^^^^^^^ +*Event header prototype for all event types* + +.. code-block:: + + { + "eventId" : "00001", + "eventCorrelationId : "cmhandle-001", + "eventTime" : "2021-11-16T16:42:25-04:00", + "eventSource" : "org.onap.ncmp", + "eventType" : "org.onap.ncmp.cmhandle-lcm-event.create", + "eventSchema" : "org.onap.ncmp:cmhandle-lcm-event", + "eventSchemaVersion" : "1.0", + "event" : ... + } + +Events payload +^^^^^^^^^^^^^^ +Event payload varies based on the type of event. + +**CREATE** + +Event payload for this event contains the properties of the new cm handle created. + +*Create event payload prototype* + +.. code-block:: json + + "event": { + "cmHandleId" : "cmhandle-001", + "newValues" : { + "cmHandleState" : "ADVISED", + "dataSyncEnabled" : "TRUE", + "cmhandleProperties" : [ + "prop1" : "val1", + "prop2" : "val2" + ] + } + } + } + + +**UPDATE** + +Event payload for this event contains the difference in state and properties of the cm handle. + +*Update event payload prototype* + +.. code-block:: json + + "event": { + "cmHandleId" : "cmhandle-001", + "oldValues" : { + "cmHandleState" : "ADVISED", + "dataSyncEnabled" : "FALSE", + "cmhandleProperties" : [ + "prop1" : "val1", + "prop2" : "val2", + } + "newValues" : { + "cmHandleState" : "READY", + "dataSyncEnabled" : "TRUE", + "cmhandleProperties" : [ + "prop1" : "updatedval1", + "prop2" : "updatedval2" + ] + } + } + } + + +**DELETE** + +Event payload for this event contains the identifier of the deleted cm handle. + +*Delete event payload prototype* + +.. code-block:: json + + "event": { + "cmHandleId" : "cmhandle-001", + }
\ No newline at end of file diff --git a/docs/cps-events.rst b/docs/cps-events.rst index d487018e4f..25a253bada 100644 --- a/docs/cps-events.rst +++ b/docs/cps-events.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) 2022 Nordix Foundation +.. Copyright (C) 2022-2023 Nordix Foundation .. DO NOT CHANGE THIS LABEL FOR RELEASE NOTES - EVEN THOUGH IT GIVES A WARNING .. _cpsEvents: @@ -8,153 +8,16 @@ CPS Events ########## -CPS-NCMP -******** +.. toctree:: + :maxdepth: 1 -Async events are triggered when a valid topic has been detected in a passthrough operation. + cm-handle-lcm-events.rst + data-operation-events.rst -:download:`NCMP request response event schema <schemas/ncmp-async-request-response-event-schema-v1.json>` - -Event header -^^^^^^^^^^^^^ - -.. code-block:: json - - { - "eventId" : "001", - "eventCorrelationId" : "cps-001", - "eventTime" : "2022-09-28T12:24:21.003+0000", - "eventTarget" : "test-topic", - "eventType" : "org.onap.cps.ncmp.event.model.DmiAsyncRequestResponseEvent", - "eventSchema" : "urn:cps:org.onap.cps.ncmp.event.model.DmiAsyncRequestResponseEvent:v1", - "forwarded-Event" : { } - } - -Forwarded-Event Payload -^^^^^^^^^^^^^^^^^^^^^^^ - -.. code-block:: json - - "Forwarded-Event": { - "eventId" : "002", - "eventCorrelationId" : "cps-001", - "eventTime" : "2022-09-28T12:24:18.340+0000", - "eventTarget" : "test-topic", - "eventType" : "org.onap.cps.ncmp.event.model.DmiAsyncRequestResponseEvent", - "eventSchema" : "urn:cps:org.onap.cps.ncmp.event.model.DmiAsyncRequestResponseEvent:v1", - "eventSource" : "org.onap.cps.ncmp.dmi", - "response-data-schema" : "urn:cps:org.onap.cps.ncmp.event.model.DmiAsyncRequestResponseEvent:v1", - "response-status" : "OK", - "response-code" : "200", - "response-data" : { } - } - - -Lifecycle Management (LCM) Event -================================ - - -Overview --------- -LCM events for CM Handles are published when a CM Handle is created, deleted or another change in the cm handle state occurs. - - **3 possible event types:** - - * Create - * Update - * Delete - -LCM Event Schema ----------------- -The current published LCM event is based on the following schema: - -:download:`Life cycle management event schema <schemas/lcm-event-schema-v1.json>` - -LCM Event structure -------------------- - -Events header -^^^^^^^^^^^^^ -*Event header prototype for all event types* - -.. code-block:: - - { - "eventId" : "00001", - "eventCorrelationId : "cmhandle-001", - "eventTime" : "2021-11-16T16:42:25-04:00", - "eventSource" : "org.onap.ncmp", - "eventType" : "org.onap.ncmp.cmhandle-lcm-event.create", - "eventSchema" : "org.onap.ncmp:cmhandle-lcm-event", - "eventSchemaVersion" : "1.0", - "event" : ... - } - -Events payload -^^^^^^^^^^^^^^ -Event payload varies based on the type of event. - -**CREATE** - -Event payload for this event contains the properties of the new cm handle created. - -*Create event payload prototype* - -.. code-block:: json - - "event": { - "cmHandleId" : "cmhandle-001", - "newValues" : { - "cmHandleState" : "ADVISED", - "dataSyncEnabled" : "TRUE", - "cmhandleProperties" : [ - "prop1" : "val1", - "prop2" : "val2" - ] - } - } - } - - -**UPDATE** - -Event payload for this event contains the difference in state and properties of the cm handle. - -*Update event payload prototype* - -.. code-block:: json - - "event": { - "cmHandleId" : "cmhandle-001", - "oldValues" : { - "cmHandleState" : "ADVISED", - "dataSyncEnabled" : "FALSE", - "cmhandleProperties" : [ - "prop1" : "val1", - "prop2" : "val2", - } - "newValues" : { - "cmHandleState" : "READY", - "dataSyncEnabled" : "TRUE", - "cmhandleProperties" : [ - "prop1" : "updatedval1", - "prop2" : "updatedval2" - ] - } - } - } - - -**DELETE** - -Event payload for this event contains the identifier of the deleted cm handle. - -*Delete event payload prototype* - -.. code-block:: json - - "event": { - "cmHandleId" : "cmhandle-001", - } +.. note:: + Legacy async response on a client supplied topic for single cm handle data request are no longer supported. Click link below for the legacy specification. + .. toctree:: + :maxdepth: 0 + ncmp-async-events.rst
\ No newline at end of file diff --git a/docs/cps-ncmp-message-status-codes.rst b/docs/cps-ncmp-message-status-codes.rst new file mode 100644 index 0000000000..99d802f766 --- /dev/null +++ b/docs/cps-ncmp-message-status-codes.rst @@ -0,0 +1,41 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 +.. Copyright (C) 2023 Nordix Foundation + +.. DO NOT CHANGE THIS LABEL FOR RELEASE NOTES - EVEN THOUGH IT GIVES A WARNING +.. _dataOperationMessageStatusCodes: + + +CPS-NCMP Message Status Codes +############################# + + +-----------------+------------------------------------------------------+-----------------------------------+ + | Status Code | Status Message | Feature | + +=================+======================================================+===================================+ + | 0 | Successfully applied changes | Data Operation | + +-----------------+------------------------------------------------------+-----------------------------------+ + | 1 | successfully applied subscription | CM Data Notification Subscription | + +-----------------+------------------------------------------------------+-----------------------------------+ + | 100 | cm handle id(s) is(are) not found | Data Operation | + +-----------------+------------------------------------------------------+-----------------------------------+ + | 101 | cm handle id(s) is(are) in non ready state | Data Operation | + +-----------------+------------------------------------------------------+-----------------------------------+ + | 102 | dmi plugin service is not responding | Data Operation | + +-----------------+------------------------------------------------------+-----------------------------------+ + | 103 | dmi plugin service is not able to read resource data | Data Operation | + +-----------------+------------------------------------------------------+-----------------------------------+ + | 104 | partially applied subscription | CM Data Notification Subscription | + +-----------------+------------------------------------------------------+-----------------------------------+ + | 105 | subscription not applicable for all cm handles | CM Data Notification Subscription | + +-----------------+------------------------------------------------------+-----------------------------------+ + | 106 | subscription pending for all cm handles | CM Data Notification Subscription | + +-----------------+------------------------------------------------------+-----------------------------------+ + +.. note:: + + - Single response format for all scenarios both positive and error, just using optional fields instead. + - status-code 0-99 is reserved for any success response. + - status-code from 100 to 199 is reserved for any failed response. + + + diff --git a/docs/data-operation-events.rst b/docs/data-operation-events.rst new file mode 100644 index 0000000000..51ec1254af --- /dev/null +++ b/docs/data-operation-events.rst @@ -0,0 +1,64 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 +.. Copyright (C) 2023 Nordix Foundation + +.. DO NOT CHANGE THIS LABEL FOR RELEASE NOTES - EVEN THOUGH IT GIVES A WARNING +.. _dataOperationEvents: + +CPS-NCMP Data Operations Events +############################### + +These events are based on the cloud events standard which is a specification for describing event data in common formats to provide interoperability across services, platforms and systems. + +Please refer to the `cloud events <https://cloudevents.io/>`_ for more details. + +Data operation response events +****************************** + +:download:`Data operation event schema <schemas/data-operation-event-schema-1.0.0.json>` + +Event headers example +^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: json + + { + "specversion": "1.0", + "id": "77b8f114-4562-4069-8234-6d059ff742ac", + "type": "org.onap.cps.ncmp.events.async1_0_0.DataOperationEvent", + "source": "DMI", + "dataschema": "urn:cps:org.onap.cps.ncmp.events.async1_0_0.DataOperationEvent:1.0.0", + "time": "2020-12-01T00:00:00.000+0000", + "content-type": "application/json", + "data": "{some-key:some-value}", + "correlationid": "6ea5cb30ecfd4a938de36fdc07a5008f", + "destination": "client-topic" + } + +Data operation event headers +============================ + + +----------------+-----------------+------------------------------------------------------------------------+ + | Field name | Mandatory | Description | + +================+=================+========================================================================+ + | specversion | Yes | default : 1.0 | + +----------------+-----------------+------------------------------------------------------------------------+ + | id | Yes | UUID | + +----------------+-----------------+------------------------------------------------------------------------+ + | type | Yes | org.onap.cps.ncmp.events.async1_0_0.DataOperationEvent | + +----------------+-----------------+------------------------------------------------------------------------+ + | source | Yes | NCMP / DMI | + +----------------+-----------------+------------------------------------------------------------------------+ + | dataschema | No | `urn:cps:org.onap.cps.ncmp.events.async1_0_0.DataOperationEvent:1.0.0` | + +----------------+-----------------+------------------------------------------------------------------------+ + | time | No | ISO_TIMESTAMP_PATTERN = "yyyy-MM-dd'T'HH:mm:ss.SSSZ" | + +----------------+-----------------+------------------------------------------------------------------------+ + | content-type | No | default : application/json | + +----------------+-----------------+------------------------------------------------------------------------+ + | data | Yes | actual event/payload now would be under "data" field. | + +----------------+-----------------+------------------------------------------------------------------------+ + | correlationid | Yes | request id | + +----------------+-----------------+------------------------------------------------------------------------+ + | destination | Yes | client topic | + +----------------+-----------------+------------------------------------------------------------------------+ + diff --git a/docs/modeling.rst b/docs/modeling.rst index 6d31f83f4b..ceaaefda5a 100644 --- a/docs/modeling.rst +++ b/docs/modeling.rst @@ -1,7 +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 +.. Modifications Copyright (C) 2021-2023 Nordix Foundation .. _modeling: .. toctree:: @@ -121,13 +121,20 @@ Basic Concepts | Passthrough-running | config-true | read-write | +--------------------------------+-------------------------------------+-------------------------+ -Querying CM Handles - -- **CM Handle Searches Endpoints** are used to query CM Handles. +Additional information on CPS-NCMP interfaces +--------------------------------------------- .. toctree:: :maxdepth: 1 ncmp-cmhandle-querying.rst ncmp-inventory-querying.rst + ncmp-data-operation.rst + +CPS-NCMP Scheduled Processes +---------------------------- + +.. toctree:: + :maxdepth: 1 + cps-scheduled-processes.rst diff --git a/docs/ncmp-async-events.rst b/docs/ncmp-async-events.rst new file mode 100644 index 0000000000..49bf57085b --- /dev/null +++ b/docs/ncmp-async-events.rst @@ -0,0 +1,54 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 +.. Copyright (C) 2023 Nordix Foundation + +.. DO NOT CHANGE THIS LABEL FOR RELEASE NOTES - EVEN THOUGH IT GIVES A WARNING +.. _asyncEvents: + + +CPS Async Events +################ + +.. toctree:: + :maxdepth: 1 + +Introduction +============ + +Async events are triggered when a valid topic has been detected in a passthrough operation. + +:download:`NCMP request response event schema <schemas/ncmp-async-request-response-event-schema-v1.json>` + +Event header +^^^^^^^^^^^^ + +.. code-block:: json + + { + "eventId" : "001", + "eventCorrelationId" : "cps-001", + "eventTime" : "2022-09-28T12:24:21.003+0000", + "eventTarget" : "test-topic", + "eventType" : "org.onap.cps.ncmp.event.model.DmiAsyncRequestResponseEvent", + "eventSchema" : "urn:cps:org.onap.cps.ncmp.event.model.DmiAsyncRequestResponseEvent:v1", + "forwarded-Event" : { } + } + +Forwarded-Event Payload +^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: json + + "Forwarded-Event": { + "eventId" : "002", + "eventCorrelationId" : "cps-001", + "eventTime" : "2022-09-28T12:24:18.340+0000", + "eventTarget" : "test-topic", + "eventType" : "org.onap.cps.ncmp.event.model.DmiAsyncRequestResponseEvent", + "eventSchema" : "urn:cps:org.onap.cps.ncmp.event.model.DmiAsyncRequestResponseEvent:v1", + "eventSource" : "org.onap.cps.ncmp.dmi", + "response-data-schema" : "urn:cps:org.onap.cps.ncmp.event.model.DmiAsyncRequestResponseEvent:v1", + "response-status" : "OK", + "response-code" : "200", + "response-data" : { } + }
\ No newline at end of file diff --git a/docs/ncmp-data-operation.rst b/docs/ncmp-data-operation.rst new file mode 100644 index 0000000000..617b3ed309 --- /dev/null +++ b/docs/ncmp-data-operation.rst @@ -0,0 +1,148 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 +.. Copyright (C) 2023 Nordix Foundation + +.. DO NOT CHANGE THIS LABEL FOR RELEASE NOTES - EVEN THOUGH IT GIVES A WARNING +.. _cmHandleDataOperation: + + +CM Handles Data Operation Endpoints +################################### + +.. toctree:: + :maxdepth: 1 + +Introduction +============ + +For data operation CM Handles we have a Post endpoints: + +- /ncmp/v1/data?topic={client-topic-name} forward request to it's dmi plugin service. + +- Returns request id (UUID) with http status 202. + +Request Body +============ + +This endpoint executes data operation for given array of operations: + + +--------------------------+-------------+-------------------------------------------------------------------------+ + | Operation attributes | Mandatory | Description | + +==========================+=============+=========================================================================+ + | operation | Yes | Only read operation is allowed. | + +--------------------------+-------------+-------------------------------------------------------------------------+ + | operationId | Yes | Unique operation id for each operation. | + +--------------------------+-------------+-------------------------------------------------------------------------+ + | datastore | Yes | Supports only ncmp-datastore:passthrough-operational and | + | | | ncmp-datastore:passthrough-running. | + +--------------------------+-------------+-------------------------------------------------------------------------+ + | options | No | It is mandatory to wrap key(s)=value(s) in parenthesis'()'. The format | + | | | of options parameter depend on the associated DMI Plugin implementation.| + +--------------------------+-------------+-------------------------------------------------------------------------+ + | resourceIdentifier | No | The format of resource identifier depend on the associated DMI Plugin | + | | | implementation. For ONAP DMI Plugin it will be RESTConf paths but it can| + | | | really be anything. | + +--------------------------+-------------+-------------------------------------------------------------------------+ + | targetIds | Yes | List of cm handle ids. | + +--------------------------+-------------+-------------------------------------------------------------------------+ + +The status codes used in the events resulting from these operations are defined here: + +.. toctree:: + :maxdepth: 1 + + cps-ncmp-message-status-codes.rst + +Request Body example from client app to NCMP endpoint: + +.. code-block:: bash + + curl --location 'http: //{ncmp-host-name}:{ncmp-port}/ncmp/v1/data?topic=my-topic-name' \ + --header 'Content-Type: application/json' \ + --header 'Authorization: Basic Y3BzdXNlcjpjcHNyMGNrcyE=' \ + --data '{ + "operations": [ + { + "operation": "read", + "operationId": "operational-12", + "datastore": "ncmp-datastore:passthrough-operational", + "options": "some option", + "resourceIdentifier": "parent/child", + "targetIds": [ + "836bb62201f34a7aa056a47bd95a81ed", + "202acb75b4a54e43bb1ff8c0c17a8e08" + ] + }, + { + "operation": "read", + "operationId": "running-14", + "datastore": "ncmp-datastore:passthrough-running", + "targetIds": [ + "ec2e9495679a43c58659c07d87025e72", + "0df4d39af6514d99b816758148389cfd" + ] + } + ] + }' + + +DMI service batch endpoint +-------------------------- + +DMI Service 1 (POST): `http://{dmi-host-name}:{dmi-port}/dmi/v1/data?topic=my-topic-name&requestId=4753fc1f-7de2-449a-b306-a6204b5370b3` + +.. code-block:: json + + [ + { + "operationType": "read", + "operationId": "running-14", + "datastore": "ncmp-datastore:passthrough-running", + "cmHandles": [ + { + "id": "ec2e9495679a43c58659c07d87025e72", + "cmHandleProperties": { + "neType": "RadioNode" + } + }, + { + "id": "0df4d39af6514d99b816758148389cfd", + "cmHandleProperties": { + "neType": "RadioNode" + } + } + ] + } + ] + +DMI Service 2 (POST) : `http://{dmi-host-name}:{dmi-port}/dmi/v1/data?topic=my-topic-name&requestId=4753fc1f-7de2-449a-b306-a6204b5370b3` + +.. code-block:: json + + [ + { + "operationType": "read", + "operationId": "operational-12", + "datastore": "ncmp-datastore:passthrough-operational", + "options": "some option", + "resourceIdentifier": "parent/child", + "cmHandles": [ + { + "id": "836bb62201f34a7aa056a47bd95a81ed", + "cmHandleProperties": { + "neType": "RadioNode" + } + }, + { + "id": "202acb75b4a54e43bb1ff8c0c17a8e08", + "cmHandleProperties": { + "neType": "RadioNode" + } + } + ] + } + ] + +Above examples are for illustration purpose only please refer link below for latest schema. + +:download:`Data operation event schema <schemas/data-operation-event-schema-1.0.0.json>`
\ No newline at end of file diff --git a/docs/schemas/data-operation-event-schema-1.0.0.json b/docs/schemas/data-operation-event-schema-1.0.0.json new file mode 100644 index 0000000000..f82e481415 --- /dev/null +++ b/docs/schemas/data-operation-event-schema-1.0.0.json @@ -0,0 +1,69 @@ +{ + "$schema": "https://json-schema.org/draft/2019-09/schema", + "$id": "urn:cps:org.onap.cps.ncmp.events.async:data-operation-event-schema:1.0.0", + "$ref": "#/definitions/DataOperationEvent", + "definitions": { + "DataOperationEvent": { + "description": "The payload of data operation event.", + "type": "object", + "javaType" : "org.onap.cps.ncmp.events.async1_0_0.DataOperationEvent", + "properties": { + "data": { + "description": "The payload content of the requested data.", + "type": "object", + "properties": { + "responses": { + "description": "An array of batch responses which contains both success and failure", + "type": "array", + "items": { + "type": "object", + "properties": { + "operationId": { + "description": "Used to distinguish multiple operations using same handle ids", + "type": "string" + }, + "ids": { + "description": "Id's of the cmhandles", + "type": "array", + "items": { + "type": "string" + } + }, + "statusCode": { + "description": "which says success or failure (0-99) are for success and (100-199) are for failure", + "type": "string" + }, + "statusMessage": { + "description": "Human readable message, Which says what the response has", + "type": "string" + }, + "result": { + "description": "Contains the requested data response.", + "type": "object", + "existingJavaType": "java.lang.Object", + "additionalProperties": false + } + }, + "required": [ + "operationId", + "ids", + "statusCode", + "statusMessage" + ], + "additionalProperties": false + } + } + }, + "required": [ + "responses" + ], + "additionalProperties": false + } + }, + "required": [ + "data" + ], + "additionalProperties": false + } + } +}
\ No newline at end of file |