Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Create 'bulk' version for org.onap.cps.ncmp.rest.controller.NetworkCmProxyController#getResourceDataForCmHandle to support multiple cm-handles (~ multiple anchors in in CPS-Core)

...

#

Assumption

Notes

1

Proprietary options or not in the scope of this analysis.

agreed with kieran mccarthy ; these are optional parameters (name-value pairs) not interpreted by NCMP but can be interpreted by proprietary plugins
In the future "scope" might become standardized instead of proprietary but that wil be achieved through a separate requirement 

2

same xpath (resourceIdentifierInQuery) for all cm handles or different for each cm handle

agreed with kieran mccarthy ; if different resources are required on the same cm-handle the client wil send another (batch) request

3
  • options, resourceIdentifier is optional for bulk operations.
  • operation, datastore and cmhandleIds are mandatory fields

agreed with CPS team.

4We are not merging any duplicate cm handles while sending request to dmi-plugin

agreed  

5

Get batch operation does not support includeDescendants as it is impl. for 

pass through datastore only

ncmp-datastore:passthrough-running and
ncmp-datastore:passthrough-operational

agreed on  

Issues & Decisions

#

Issue

Notes 

Decision

1Which operation(s) need support for multiple cm handles?
  1. Get
  2. Create
  3. Update (Put)
  4. Patch
  5. Delete

if many what is the priority?

agreed with kieran mccarthy 

Only Get (read)

(in future other operations might be support batch option too)

2

Which datasources should be supported?

Do we need to support passthrough-only no-cached() data only ?
(maybe just start with that, support cached data bulk request later)

agreed with kieran mccarthy :

all passthrough datastores will be supported

Not implemented (yet) response, for non passthrough datastores 

3URL  pattern for NCMP bulk endpoints

Existing : /v1/ch/{cm-handle}/data/ds/{datastore-name}

CPS Proposed : /v1/batch/data/ds/{datastore-name}

      ( include cm handles into payload / body and leave datastore into url)

-----------------------------------------------------------------------------------------------------------------------

Meeting : kafka message schema & batch interface extension

POST http://localhost:8080/ncmp/v1/batch/data&topic=my-topic-name

{
              operations: [
                             {
                                           operation: read,
                                           datastore: "...",
                                           options: "...",
                                           resourceIdentifier: "...",
                                           cmhandleIds: [4, 6]
                             },
                             {
                                           operation: read,
                                           datastore: "...",
                                           options: "...",
                                           resourceIdentifier: "...",
                                           cmhandleIds: [1, 2, 3]
                             }
              ]
}

 

POST http://localhost:8080/ncmp/v1/data&topic=my-topic-name

agreed with kieran mccarthy : Follow the existing interfaces as much as possible for consistency and efficiency

------------------------------------------------------------------------------------------------------------

kieran mccarthy 


We had an internal review with some of our rApp colleagues around some of the recent proposed NCMP batch interface and they came back with some valid comment. 


The proposal is that we should not distinguish batch from bulk or other flavours of read/write. 

The aim is to only have a single flavour of interface for read or write for clients.  Therefore the proposal is to drop “batch” from the interface URL and just act toward “data”  (reads/writes/actions)


4keep datastore, topic and optional parameters in the URL itself instead into body.

CPS prefers keep interface similar as single cm handle interface (consistency and cost)

Existing : ...&topic=topicParamInQuery

agreed with kieran mccarthy : Follow the existing interfaces as much as possible for consistency and efficiency

5

support in ONAP DMI-plugin


agreed with Toine Siebelink : ONAP plugin can respond with not implemented yet code,

6

Response always Async ie. topic is compulsory ?

Assume topic is compulsory (defined in OPenApi) → Response therefore wil be 400 if not supplied

Agreed with kieran mccarthy :

Topic is optional but system will respond with 'Not implemented (yet when not specified or blank

7Should NCMP Amalgamate Async responses from DMI-Plugin before forwarding ?step 6 in flow diagram

Agreed with kieran mccarthy : NCMP wil only forward to client topic no handling tracking or any responses or status of request

8Handle non responding dmi-plugin

Agreed with kieran mccarthy :
No response for 4b then send an error response to the topic given by client

9Should (can) NCMP check if 'MyTopic' specified by client existConsider Access Control too. For now NCMP can log error. Client is responsible for topic setup

Agreed with kieran mccarthy :
NCMP can log error when forward to 'client topic' Security not in scope (yet)

10How to handle non-existing CM-Handles (id)

Suggestions

  1. Silently ignore
  2. (initial) error response
    1. should we combine all errors in one message?

Agreed with kieran mccarthy :

Additional error (messages) response with all cm-handles that cannot be resolved, also a separate error message wil be sent for each failed DMI

11

Overlap/clash with Deutsche Telekom user story:

Jira Legacy
serverSystem Jira
serverId4733707d-2057-3a0f-ae5e-4fd8aff50176
keyCPS-1377
?!


discussed in weekly ONAP meeting the DT user story is affect CPS-Core interface (not NCMP) and the requirement is to execute a query over ALL cm-handles (cached  only?!) instead of a given list of cm-handles (~anchors)

12

Schema of bulk response


Jira Legacy
serverSystem Jira
columnIdsissuekey,summary,issuetype,created,updated,duedate,assignee,reporter,priority,status,resolution
columnskey,summary,type,created,updated,due,assignee,reporter,priority,status,resolution
serverId4733707d-2057-3a0f-ae5e-4fd8aff50176
keyCPS-1556

1) Agreement required on the structure of the response.  Please see response structure below.
2) Does 'eventTime' field which holds the timestamp of the bulk response event,  required or can it be dropped?


Code Block
titleBatch Event Headers Schema
collapsetrue
{
  "$schema": "https://json-schema.org/draft/2019-09/schema",
  "$id": "urn:cps:org.onap.cps.ncmp.events.async:batch-event-headers:1.0.0",
  "$ref": "#/definitions/BatchEventHeaders",
  "definitions": {
    "BatchEventHeaders": {
      "description": "The header information of the Batch event.",
      "type": "object",
      "javaType" : "org.onap.cps.ncmp.events.async.v1.BatchEventHeaders",
      "properties": {
        "eventId": {
          "description": "The unique id for identifying the event.",
          "type": "string"
        },
        "eventCorrelationId": {
          "description": "The request id received by NCMP as an acknowledgement.",
          "type": "string"
        },
        "eventTime": {
          "description": "The time of the event. It should be in RFC format ('yyyy-MM-		     dd'T'HH:mm:ss.SSSZ').",
          "type": "string"
        },
        "eventTarget": {
          "description": "The destination topic to forward the consumed event.",
          "type": "string"
        },
        "eventSource": {
          "description": "The source of the event.",
          "type": "string"
        },
        "eventType": {
          "description": "The type of the Batch event.",
          "type": "string"
        },
        "eventSchema": {
          "description": "The schema of the Batch event payload.",
          "type": "string"
        },
        "eventSchemaVersion": {
          "description": "The schema version of the Batch event payload.",
          "type": "string"
        }
      },
      "required": [
        "eventId",
        "eventCorrelationId",
        "eventTarget",
        "eventType",
        "eventSchema",
        "eventSchemaVersion"
      ],
      "additionalProperties": false
    }
  }
}


Code Block
titleSample Batch Event Headers
collapsetrue
{
  "eventId":            "4cb32729-85e3-44d1-aa6e-c923b9b059a5",
  "eventCorrelationId": "68f15800-8ed4-4bae-9e53-27a9e03e1911",
  "eventTime":          "2023-03-28T14:29:23.876+0000",
  "eventTarget":        "client-topic"
  "eventSource":        "dmi-plugin:enm-1"(dmi service name)
  "eventType":          "org.onap.cps.ncmp.event.model.BulkResponseEvent",
  "eventSchema":        "urn:cps:org.onap.cps.ncmp.events.async:batch-event-schema:1.0.0",
  "schemaVersion":      "1.0.0",

}


Code Block
titleBatch Event Payload Schema
collapsetrue
{
  "$schema": "https://json-schema.org/draft/2019-09/schema",
  "$id": "urn:cps:org.onap.cps.ncmp.events.async:batch-event-schema:1.0.0",
  "$ref": "#/definitions/BatchDataResponseEvent",
  "definitions": {
    "BatchDataResponseEvent": {
      "description": "The payload of batch event.",
      "type": "object",
      "javaType" : "org.onap.cps.ncmp.events.async.v1.BatchEvent",
      "properties": {
        "event": {
          "description": "The content of Batch event.",
          "type": "object",
          "existingJavaType": "java.lang.Object",
          "additionalProperties": false
        }
      },
      "required": [
        "event"
      ],
      "additionalProperties": false
    }
  }
}  


Code Block
titleSample Batch Event Payload
collapsetrue
{     
  "event": {
     "payload": "response of batch cm handles"
  } 
}


Need to follow schema structure there in  #15 under Issues & Decisions section and it  is  agreed on    

13

Schema for Bulk Response event forwarding to client specified  topic

CPS-1557 - NCMP : forward bulk response messages to client topic

Not keeping the 'eventTarget' which comes from the (BulkResponseEvent(In progress of the structure agreement)).

Note:  Will consider  'eventTarget', If it finalized the schema from

Jira Legacy
serverSystem Jira
columnIdsissuekey,summary,issuetype,created,updated,duedate,assignee,reporter,priority,status,resolution
columnskey,summary,type,created,updated,due,assignee,reporter,priority,status,resolution
serverId4733707d-2057-3a0f-ae5e-4fd8aff50176
keyCPS-1556




Agreed on to keep one schema for both events (DMI → NCMP) and (NCMP → ClientApps)

14

How NCMP would forward response? (Response data : ref.  message flow #6)

Jira Legacy
serverSystem Jira
columnIdsissuekey,summary,issuetype,created,updated,duedate,assignee,reporter,priority,status,resolution
columnskey,summary,type,created,updated,due,assignee,reporter,priority,status,resolution
serverId4733707d-2057-3a0f-ae5e-4fd8aff50176
keyCPS-1556

    1. Do we need to send only one response containing all the requested cm handles ?
    2. Send single response for each cm handle?
    3. Single response message per DMI plugin?

kieran mccarthy - Please share your inputs on the above listed questions.


15Message format for the batch interfacesome non-standard headers wil need to be implemented as 'extensions' and names to be confirmed
  • correlationid
  • target

 kieran mccarthy 

We have had some internal discussions including with some O-RAN standards representatives and one of the outcomes is that it would be good if we aligned with the some community standards for event header definitions.  IT is proposed (initially from AT&T) that we should follow Cloud Native Computing Foundation (CNCF) specification as defined in their cloudevents incubator project.
More details see CPS Events Structure#CNCFCloudEventalignment        

16NCMP wil send only one request to each DMI


Code Block
languagebash
titleNCMP batch endpoint
collapsetrue
curl --location 'http: //localhost:8080/ncmp/v1/data?topic=my-topic-name' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic Y3BzdXNlcjpjcHNyMGNrcyE=' \
--data '{
    "operations": [
        {
            "operation": "read",
            "operationId": "12",
            "datastore": "ncmp-datastore:passthrough-operational",
            "options": "(fields=schemas/schema)",
            "resourceIdentifier": "parent/child",
            "targetIds": [
                "836bb62201f34a7aa056a47bd95a81ed",
                "202acb75b4a54e43bb1ff8c0c17a8e08"
            ]
        },
        {
            "operation": "read",
            "operationId": "14",
            "datastore": "ncmp-datastore:passthrough-running",
            "targetIds": [
                "ec2e9495679a43c58659c07d87025e72",
                "0df4d39af6514d99b816758148389cfd"
            ]
        }
    ]
}'


Code Block
languagebash
titleNCMP batch endpoint response (200->OK)
collapsetrue
{
    "requestId": "4753fc1f-7de2-449a-b306-a6204b5370b3"
}


Code Block
languagebash
titleDMI service batch endpoint
collapsetrue
DMI Service 1 (POST): http://172.26.202.25:8783/dmi/v1/data?topic=my-topic-name&requestId=4753fc1f-7de2-449a-b306-a6204b5370b3 -> 

[
    {
        "operationType": "read",
        "operationId": "14",
        "datastore": "ncmp-datastore:passthrough-running",
        "cmHandles": [
            {
                "id": "ec2e9495679a43c58659c07d87025e72",
                "cmHandleProperties": {
                    "neType": "RadioNode"
                }
            },
            {
                "id": "0df4d39af6514d99b816758148389cfd",
                "cmHandleProperties": {
                    "neType": "RadioNode"
                }
            }
        ]
    }
]

DMI Service 2 (POST) : http://172.26.202.26:8783/dmi/v1/data?topic=my-topic-name&requestId=4753fc1f-7de2-449a-b306-a6204b5370b3 -> 

   [
    {
        "operationType": "read",
        "operationId": "12",
        "datastore": "ncmp-datastore:passthrough-operational",
        "options": "(fields=schemas/schema)",
        "resourceIdentifier": "parent/child",
        "cmHandles": [
            {
                "id": "836bb62201f34a7aa056a47bd95a81ed",
                "cmHandleProperties": {
                    "neType": "RadioNode"
                }
            },
            {
                "id": "202acb75b4a54e43bb1ff8c0c17a8e08",
                "cmHandleProperties": {
                    "neType": "RadioNode"
                }
            }
        ]
    }
]


Agreed with Csaba Kocsis  and kieran mccarthy

requestId would be send as a path param from NCMP to DMI-plugin.


Example 

NCMP batch endpoint : http://localhost:8080/ncmp/v1/data?&topic=my-topic-name

DMI-Plugin batch endpoint : http://172.26.202.25:8783/dmi/v1/data?topic=my-topic-name&requestId=e6fa4d26-4dc1-4877-aa3c-45e99f840708


  • Mandatory Fileds :
      • "operation": "read"
      • "operationId": "12"
        "datastore": "ncmp-datastore:passthrough-operational"
      • "targetIds": [ "0df4d39af6514d99b816758148389cfd", "ec2e9495679a43c58659c07d87025e72" ]


  • Optional Fields : 
      • "options": "(fields=schemas/schema)"
      • "resourceIdentifier": "parent/child"




17Feature Name (events, URL)

event type proposal : from BatchDataXXXEvent  to

DataOperationXXXEvent

For example : DataOperationResponseEvent 

 'eventType' value as below 'org.onap.cps.ncmp.events.BatchDataXXXEvent

proposed Operation like :

'org.onap.cps.ncmp.events.DataOperationXXXEvent

'batch' was the keyword use in the URL for this feature (now gone) but much code classes etc uses this name still...


...

Field 

Type

Description

Mandatory?

Notes

event
EventThe payload of an event

Mandatory


event.responses[0, 1, 2, ...]
Array contains an array or batch response that includes both success and failure.

Mandatory


event.responses[0].operationId
Stringspecified to distinguish multiple operations using same cmhandleId

Mandatory


event.responses[0].ids
Stringcmhandle-ids

Mandatory

Example : ["0df4d39af6514d99b816758148389cfd"]
Note: Ids array should contain only a single element in the array in case of success messages and In case of error it can have any number of elements.

event.responses[0].status-code
String

Mandatory

Common NCMP defined error codes:

  • status-code 0-99 is reserved for any success response
  • status-code from 100 to 199 is reserved for any failed response. 
event.responses[0].status-message
String

Mandatory

Examples for code & message :

status-codestatus-message
1"Successfully applied changes"
101"cmHandle(s) do not exist"


event.responses[0].dataObject

Optional

  1. In case of success :
    • Optional,  for write operations then no need to return configurations                    application/yang-patch+json | application/yang-data+json
  2. In case of failure :
    • Optional, any supplementary error data matching the error status-code

Implementation

Bulk Request Message Flow

...

Flow Step

Short description

Message Details

Notes

1

Bulk Get Request


Code Block
title/v1/batch/data/ds/{datastore-name}
collapsetrue
body:
["cm-1",...,"cm-n"]


Code Block
titleExample CURL cmd : curl --location --request POST
collapsetrue
'http://localhost:8080/ncmp/v1/batch/data/ds/ncmp-datastore:passthrough-running?resourceIdentifier=parent/child%26options=(a=1,b=2)&topic=my-topic-name&options=(fields=schemas/schema)' \
--header 'Authorization: Basic Y3BzdXNlcjpjcHNyMGNrcyE=' \
--header 'Content-Type: application/json' \
--data '[ "40137a9771f84459affa795fa1d633ab", "f5a92ec7a7db4d6fbb0e0ce2803a86cc" ]'


Define new get operation "getResourceDataForCmHandles" into ncmp.yml

2Ack clent Request


Code Block
titleResponse 200
collapsetrue
{"requestId":"123"}



3DMI Bulk Request


Code Block
title/v1/ch/batch/data/ds/{datastore-name}&topic=topicParamInQuery
collapsetrue
body: {"Cmhandles":["cm-1",...,"cm-n"],"requestId":123}


The DMI PLugin should be told (included in request) the client topic so that NCMP does not have to 'remember' to relation between request id and client topic!



4Ack NCMP Request


Code Block
titleResponse 202
collapsetrue


202 is non-committal, meaning that there is no way for the HTTP to later send an asynchronous response indicating the outcome of processing the request. It is intended for cases where another process or server handles the request, or for batch processing.
5Kafka Messages from DMI to NCMP


Code Block
titleBatch Event Headers
collapsetrue
{
  "eventId":            "4cb32729-85e3-44d1-aa6e-c923b9b059a5",
  "eventCorrelationId": "68f15800-8ed4-4bae-9e53-27a9e03e1911",
  "eventTime":          "2023-03-28T14:29:23.876+0000",
  "eventTarget":        "client-topic"
  "eventSource":        "dmi-plugin:enm-1"(dmi service name)
  "eventType":          "org.onap.cps.ncmp.event.model.BulkResponseEvent",
  "eventSchema":        "urn:cps:org.onap.cps.ncmp.events.async:batch-event-schema:1.0.0",
  "schemaVersion":      "1.0.0",

}


Code Block
titleBatch Event Payload
collapsetrue
{     
  "event": {
     "payload": "response of batch cm handles"
  } 
}



6Kafka Message(s) from NCMP to Client 
Table


Code Block
titleBatch Event Headers
collapsetrue
{
  "eventId":            "4cb32729-85e3-44d1-aa6e-c923b9b059a5",
  "eventCorrelationId": "68f15800-8ed4-4bae-9e53-27a9e03e1911",
  "eventTime":          "2023-03-28T14:29:23.876+0000",
  "eventSource":        "dmi-plugin:enm-1"(dmi service name)
  "eventType":          "org.onap.cps.ncmp.event.model.BulkResponseEvent",
  "eventSchema":        "urn:cps:org.onap.cps.ncmp.events.async:batch-event-schema:1.0.0",
  "schemaVersion":      "1.0.0",

}


Code Block
titleBatch Event Payload
collapsetrue
{     
  "event": {
     "payload": "response of batch cm handles"
  } 
}



7Alternative for 4/5 → Non responding DMI. NCMP will have to create error message detailing cm-handles
See decision # 8 and 9
8

Response message structure ? (Flow no. 5)

Non responding DMI-plugin 


Code Block
titleNon responding DMI-plugin 
collapsetrue
{
  "timestamp":"2023-03-01T23:00:00.345-0400", 
  "requestId":123,
  "error": "DMI Service Unavailable, {service-name}",
  "Cmhandles":["cm-1",...,"cm-n"]
  }



9

Response message structure ? (Flow no. 5)

Non existing cm handles


Code Block
titleNon existing cm handles
collapsetrue
{
	"timestamp":"2023-03-01T23:00:00.345-0400",
    "requestId":123,
	"error":"Cm-Handle not found",
	"Cmhandles":["cm-1",...,"cm-n"]
}



10Non Ready cm handles


Code Block
titleNon READY existing cm handles
collapsetrue
{
	"timestamp":"2023-03-01T23:00:00.345-0400",
    "requestId":123,
	"error":"Cm-Handle not in READY state.",
	"Cmhandles":["cm-1",...,"cm-n"]
}



11URL  pattern for DMI-Plugin bulk endpoints

Existing DMI endpoints are : 

/v1/ch/{cmHandle}/data/ds/{datastore-name}


datastore-name:

  1. ncmp-datastore:passthrough-operational
  2. ncmp-datastore:passthrough-running

 ...&topic=topicParamInQuery


CPS Proposed :

/v1/ch/batch/data/ds/{datastore-name}

 ...&topic=topicParamInQuery

cm handle ids and requestid into body


...

PriorityComponentDescriptionJIRAsEstimateStatus
1DMI, NCMPBatch Response Event (DMI → NCMP) to Comply with Cloud Events

Jira Legacy
serverSystem Jira
columnIdsissuekey,summary,issuetype,created,updated,duedate,assignee,reporter,priority,status,resolution
columnskey,summary,type,created,updated,due,assignee,reporter,priority,status,resolution
serverId4733707d-2057-3a0f-ae5e-4fd8aff50176
keyCPS-1723

5 Days (M)New Requirement. 
2NCMPBatch Response Event (NCMP → Client App)

Jira Legacy
serverSystem Jira
columnIdsissuekey,summary,issuetype,created,updated,duedate,assignee,reporter,priority,status,resolution
columnskey,summary,type,created,updated,due,assignee,reporter,priority,status,resolution
serverId4733707d-2057-3a0f-ae5e-4fd8aff50176
keyCPS-1724

TBDNew Requirement. 
3DMI-PluginAccept  datastore name as param into URL 

Jira Legacy
serverSystem Jira
serverId4733707d-2057-3a0f-ae5e-4fd8aff50176
keyCPS-1550

5 DaysDone
4NCMP Expose REST endpoint to accept collection of cm handles for GET operation (Passthrough only)

Jira Legacy
serverSystem Jira
serverId4733707d-2057-3a0f-ae5e-4fd8aff50176
keyCPS-1553

15 DaysPending Doc. only
5DMI-PluginExpose endpoint for ONAP not impl. and Stub impl. for testing/demo

Jira Legacy
serverSystem Jira
serverId4733707d-2057-3a0f-ae5e-4fd8aff50176
keyCPS-1555

5 DaysDone
6NCMPNCMP: Update existing REST endpoint that accepts bulk request for GET operation

Jira Legacy
serverSystem Jira
columnIdsissuekey,summary,issuetype,created,updated,duedate,assignee,reporter,priority,status,resolution
columnskey,summary,type,created,updated,due,assignee,reporter,priority,status,resolution
serverId4733707d-2057-3a0f-ae5e-4fd8aff50176
keyCPS-1635

5 Daysnew because Requirements changed
+5 days
7DMI-PluginDMI-Plugin : Update endpoint to accept bulk request

Jira Legacy
serverSystem Jira
columnIdsissuekey,summary,issuetype,created,updated,duedate,assignee,reporter,priority,status,resolution
columnskey,summary,type,created,updated,due,assignee,reporter,priority,status,resolution
serverId4733707d-2057-3a0f-ae5e-4fd8aff50176
keyCPS-1636

3 Daysnew because Requirements changed
8Stubbed DMI-PluginInclude code to send response messages to internal kafka topic with delay 

Jira Legacy
serverSystem Jira
serverId4733707d-2057-3a0f-ae5e-4fd8aff50176
keyCPS-1556

10 Days
9NCMP Forward response messages to client given kafka topic

Jira Legacy
serverSystem Jira
serverId4733707d-2057-3a0f-ae5e-4fd8aff50176
keyCPS-1557

5 Days

delayed because Schema/Headers issue

+4 daysDone

10NCMP Handle non-existing cm handles

Jira Legacy
serverSystem Jira
columnIdsissuekey,summary,issuetype,created,updated,duedate,assignee,reporter,priority,status,resolution
columnskey,summary,type,created,updated,due,assignee,reporter,priority,status,resolution
serverId4733707d-2057-3a0f-ae5e-4fd8aff50176
keyCPS-1583

5 Days
11NCMP Error handling for non-ready cm handle state

Jira Legacy
serverSystem Jira
serverId4733707d-2057-3a0f-ae5e-4fd8aff50176
keyCPS-1614

5 Days
12NCMP Handle non responding DMI-Plugin

Jira Legacy
serverSystem Jira
serverId4733707d-2057-3a0f-ae5e-4fd8aff50176
keyCPS-1558

5 Days
13CSIT test for demo

Jira Legacy
serverSystem Jira
serverId4733707d-2057-3a0f-ae5e-4fd8aff50176
keyCPS-1560

5 Days

...