ListenHTTP (NGSIRestHandler)

Content:

Functionality

Mapping NGSI events to NGSIEvent objects

This section explains how a notified NGSI event (a http message containing headers and payload) is used to create a NGSIEvent object, suitable for being consumed by any of the Draco processors, thanks to ListenHTTP.

It is necessary to remark again this handler is designed for being used by ListenHTTP, the native processor of Apache NiFi. An http message containing a NGSI-like notification will be received by ListenHTTP and passed to NGSIRestHandler in order to create one or more NGSIEvent objects (one per notified context element) to be put in a sink's channel (mainly, these channels are objects in memory, but could be files).

On the one hand, the http message containing the NGSI-like notification will be composed of a set of http headers, and a payload. On the other hand, the NGSIEvent objects are composed of a set of headers as well and an object of type ContextElement containing the already parsed version of the context elements within the notification; this parsed version of the notified body is ready for being consumed by other components in the agent architecture, such as interceptors or sinks, thus parsing is just made once.

As can be seen, there is a quasi-direct translation among http messages and NGSIEvent objects:

http message NGSIEvent object
Fiware-Service header fiware-service header
 Fiware-ServicePath header fiware-servicepath header
 Fiware-Correlator header fiware-correlator header. If this header is not sent, the fiware-correlator is equals to the transaction-id header.
transaction-id header (internally added)
any other header discarded
 payload ContextElement object containing the parsed version of the payload

All the FIWARE headers are added to the NGSIEvent object if notified. If not, default values are used (it is the case of fiware-service and fiware-servicepath, which take the configured value of default_service and default_service_path respectively, see below the configuration section) or auto-generated (it is the case of fiware-correlator, whose value is the same than transaction-id).

As already introduced, in addition to the fiware-correlator, a transaction-id is created for internally identify a complete Draco transaction, i.e. starting at the source when the context data is notified, and finishing in the sink, where such data is finally persisted. If Fiware-Correlator header is not notified, then fiware-correlator and transactionid get the same auto-generated value.

Finally, it must be said the NGSIEVent contains another field, of type ContextElement as well, in order the NGSINameMappingsInterceptor add a mapped version of the original context element added by this handler.

Example

Let's assume the following not-intercepted event regarding a received notification (the code below is an object representation, not any real data format):

notification={
   headers={
       fiware-service=hotel1,
       fiware-servicepath=/other,/suites,
       correlation-id=1234567890-0000-1234567890
   },
   body={
      {
          entityId=suite.12,
          entityType=room,
          attributes=[
             ...
          ]
       },
       {
          entityId=other.9,
          entityType=room,
          attributes=[
             ...
          ]
       }
    }
}

As can be seen, two entities (suite.12 and other.9) of the same type (room) within the same FIWARE service (hotel) but different service paths (/suites and /other) are notified. NGSIRestHandler will create two NGSIEvent's:

ngsi-event-1={
   headers={
       fiware-service=hotel,
       fiware-servicepath=/suites,
       transaction-id=1234567890-0000-1234567890,
       correlation-id=1234567890-0000-1234567890,
       timestamp=1234567890,
       mapped-fiware-service=hotel
       mapped-fiware-service-path=/suites
    },
   original-context-element={
       entityId=suite.12,
       entityType=room,
       attributes=[
          ...
       ]
    }
}

ngsi-event-2={
   headers={
       fiware-service=hotel,
       fiware-servicepath=/other,
       transaction-id=1234567890-0000-1234567890,
       correlation-id=1234567890-0000-1234567890,
       timestamp=1234567890,
       mapped-fiware-service=hotel
       mapped-fiware-service-path=/other
   },
   original-context-element={
       entityId=other.9,
       entityType=room,
       attributes=[
          ...
       ]
    }
}

Administration guide

Configuration

ListenHTTP is configured through the following parameters:

Name Default Value Allowable Values Description
Base Path contentListener Base path for incoming connectionsSupports, this has to match with the notify attribute of the subscription made in ORION Expression Language: true (will be evaluated using variable registry only)
Listening Port no The Port to listen on for incoming connectionsSupports, also need to be including in the subscription, Expression Language: true (will be evaluated using variable registry only)
Max Data to Receive per Second The maximum amount of data to receive per second; this allows the bandwidth to be throttled to a specified data rate; if not specified, the data rate is not throttled
SSL Context Service Controller Service API: RestrictedSSLContextServiceImplementation: StandardRestrictedSSLContextService The Controller Service to use in order to obtain an SSL Context
Authorized DN Pattern .*
Max Unconfirmed Flowfile Time 60 secs The maximum amount of time to wait for a FlowFile to be confirmed before it is removed from the cache
HTTP Headers to receive as Attributes (Regex) no Specifies the Regular Expression that determines the names of HTTP Headers that should be passed along as FlowFile attributes. You have to include at least Fiware-service, Fiware-Service-Path and Optionally X-Auth-Token
Return Code 200 The HTTP return code returned after every HTTP call

A configuration example could be:

listen-processor