(Only doc pending) [cygnus-ngsi][NGSISink, NGSIGroupingInterceptor] Accept NGSI v2-like notifications

[frbattid]

Cygnus must be able to accept NGSI v2-like notifications.

This affects OrionSink and GroupingInterceptor, where the notified data is parsed.

At least, a new container must be created for the new notified Json.

It is necessary to find a way of distinguishing between v1 and v2 notifications without performing a try-and-error.

[fgalan]

It is necessary to find a way of distinguishing between v1 and v2 notifications without performing a try-and-error.

It can be easily done just checking the existence of the Ngsiv2-Attrsformat header in incoming notifications.

[minimalisti]

Has there been developments in NGSIv2 notifications support in Cygnus?

The support seems to be marked as a "Medium term" goal in https://github.com/telefonicaid/fiware-cygnus/blob/master/doc/roadmap.md. At least that is how I read "NGSIv2 notification reception endpoint" :-).

[fgalan]

You are right, that feature is part of the roadmap. However, note also the following disclaimer in the roadmap document:

Note we develop this software in Agile way, so development plan is continuously under review. Thus, this roadmap has to be understood as rough plan of features to be done along time which is fully valid only at the time of writing it. This roadmap has not be understood as a commitment on features and/or dates.

We are open to contributions regarding this. The modification should be easy for somebody with Java background and we will be more than happy to provide support regarding the files to touch and the unit tests to develop if somebody in the community volunteers to do this task. Just tell us :)

[AlvaroVega]

Currently cygnus supports notifications created with attrsFormat=legacy (NGSIv1) Check if support attrsFormat=normalized (NGSIv2)

[fgalan]

As a reference, this is an example of the format currently supported (NGSIv1):

{
    "subscriptionId": "51c0ac9ed714fb3b37d7d5a8",
    "originator": "localhost",
    "contextResponses": [
        {
            "contextElement": {
                "attributes": [
                    {
                        "name": "A",
                        "type": "AT",
                        "value": "Aval",
                        "metadatas": [
                          {
                            "name": "MD1",
                            "type": "MD1T",
                            "value": "MD1val"
                          },
                          {
                            "name": "MD2",
                            "type": "MD2T",
                            "value": "MD2val"
                          }
                      ]
                    },
                    {
                        "name": "B",
                        "type": "BT",
                        "value": "Bval"
                    }
                ],
                "type": "T",
                "isPattern": "false",
                "id": "E1"
            },
            "statusCode": {
                "code": "200",
                "reasonPhrase": "OK"
            }
        }
    ]
}

(Reference: https://fiware-orion.readthedocs.io/en/1.15.1/user/walkthrough_apiv1/index.html#context-subscriptions)

And this is the equivalence in NGSIv2:

{
  "subscriptionId": "51c0ac9ed714fb3b37d7d5a8",
  "data": [
    {
      "id": "E1",
      "type": "T",
      "A": {
        "value": "Aval",
        "type": "AT",
        "metadata": {
          "MD1": {
            "value": "MD1val",
            "type": "MD1type"
          },
          "MD2": {
            "value": "MD2val",
            "type": "MD2type"
          }
        }
      },
      "B": {
        "value": "Bval",
        "type": "BT",
        "metadata": {}
      }
    }
  ]
}

(Reference: telefonicaid.github.io/fiware-orion/api/v2/stable section "Notification Messages").

As you can see, the information elements are the same: entity id, entity type, attribute name, attribute type, attribute value, metadata name, metadata type and metadata value. Only the JSON structure changes.

Some additional remarks:

• The structure are prepared for an array of entities, but except by the initial notification (that Cygnus ignores as far as I remember) there will be always one entity.
• The entity may have from 0 to N attributes (although 0 is a weird case)
• Each attribute may have from 0 to N metadata.

[fgalan]

It is necessary to find a way of distinguishing between v1 and v2 notifications without performing a try-and-error.

It can be easily done just checking the existence of the Ngsiv2-Attrsformat header in incoming notifications.

The decision algorithm should be as follows:

• If ngsiv2-attrsformat header exists and its value is normalized: use the (new) NGSIv2 processing logic
• If ngsiv2-attrsformat header exists and its value is legacy: use the current NGSIv1 processing logic
• If ngsiv2-attrsformat header exists and its value is not normalized or legacy: log a warning/error (not sure right know which log level should be better) and ignore the notification
• If ngsv2-attrsformat doesn't exists: use the current NGSIv1 processing logic

[fgalan]

This seems to be the entrypoint for requests in the Cygnsu code (NGSIRestHandle class):

public List<Event> getEvents(javax.servlet.http.HttpServletRequest request) throws Exception

[fgalan]

Code implementations and test in PR https://github.com/telefonicaid/fiware-cygnus/pull/1762

A review of the documentation to remove NGSIv1 parts is yet pending, so we'll keep the issue opened a little bit.