Name mappings

Name mappings is an advanced global feature of Cygnus. It is global because it is available for all NGSI sinks.

Name mappings allow changing the notified FIWARE service, FIWARE service path, entity IDs, entity types, attribute names and attribute types, given a mapping. Such a mapping is just a Json within a configuration file detailing how original naming must be replaced by alternative naming.

{
   "serviceMappings": [
      {
         "originalService": "frb",
         "newService": "new_frb",
         "servicePathMappings": [
            {
               "originalServicePath": "/any",
               "newServicePath": "/new_any",
               "entityMappings": [
                  {
                     "originalEntityId": "Room1",
                     "originalEntityType": "Room",
                     "newEntityId": "new_room1",
                     "newEntityType": "new_room",
                     "attributeMappings": [
                        {
                           "originalAttributeName": "temperature",
                           "originalAttributeType": "centigrade",
                           "newAttributeName": "new_temp",
                           "newAttributeType": "new_cent"
                        },
                        ...
                     ]
                  },
                  ...
               ]
            },
            ...
         ]
      },
      ...
   ]
}

When a notification is sent to Cygnus, a special Flume interceptor called NGSINameMappingsInterceptor intercepts the plain Event's generated by NGSIRestHandler, parses the Event's body and iterate on the configured mappings in order to create a mapped version of the original notification. Once finished, both versions of the notification, original and mapped ones, are put into the channel buy means of a NGSIEvent, a Java object able to handle:

  • The original headers sent by NGSIRestHandler, i.e. fiware-service, fiware-servicepath, fiware-correlator and transaction-id.
  • New headers regarding the mapped FIWARE service and FIWARE service path, i.e. mapped-fiware-service and mapped-fiware-service-path.
  • The original notification already parsed as a NotifyContextRequest object.
  • The mapped version of the original notification as a NotifyContextRequest object.

Please observe no raw bytes about the body are sent.

Whenever a sink takes one of these NGSIEvent's, it is only a matter of deciding if such a sink enables the name mappings (enable_name_mappings parameter) or not. If name mappings are enabled, then the already parsed NotifyContextRequest, mapped version, is used. If not, then the original version is used.

Important notes

Please observe the name mappings definition is global to all the sinks, at NGSIRestHandler, but then the application is local to the sink, depending on the enable_name_mappings parameter. Thus, if any of your sinks is going to take advantage of the mappings, simply leave blank the mappings configuration file in the REST handler. That will avoid unnecessary interception and iterations on the mappings.

Additionally, please observe if any of the original names is not present, then the mapping affects all the names of that type. For instance, if originalService is not present in the fist mapping, then the mapping affects all the FIWARE services.

Top

Name mappings vs. grouping rules

As seen, the name mappings feature is quite similar to the already existent grouping rules. Both of them are Flume interceptors and both of them allow changing certain notified name elements. Thus, which are the differences? Mainly:

Name mappings Grouping rules
Allow changing the notified FIWARE service, FIWARE service path, entity IDs, entity types, attribute names and attribute types. Allow changing the notified FIWARE service path and the concatenation of entity ID and entity type (this is called the destination).
Plain Flume Event's are intercepted, and NGSIEvent's are put into the channel. Because the interceptor needs to parse the original notification, a NGSIEvent already contains the original notification parsed, and the mapped version of the original notification, freeing the sinks to parse the notification. Plain Flume Event's are intercepted, and plain Event's are put into the channel. Thus, the sinks must parse the notification, despite the grouping interceptor already parsed it`.
It is expected a enable_content_mappings feature is implemented in the future. Such a content mapping will take advantage of the already mapped version on the original notification within NGSIEvent's. Such a functionality is very hard to implement based on the current grouping interceptor code.

Most probably, the grouping rules feature is deprecated in future versions of Cygnus.

Top

Further reading

Please, check the specific documentation for this custom interceptor in the Flume extensions catalogue for cygnus-ngsi agent.

Top