diff --git a/doc/api.md b/doc/api.md index ee74b7edf..5b9ac8aa4 100644 --- a/doc/api.md +++ b/doc/api.md @@ -12,6 +12,7 @@ - [Special measures and attributes names](#special-measures-and-attributes-names) - [Device to NGSI Mapping](#device-to-ngsi-mapping) - [Device autoprovision and entity creation](#device-autoprovision-and-entity-creation) + - [Entity Name expression support](#entity-name-expression-support) - [Multientity support](#multientity-support) - [Metadata support](#metadata-support) - [NGSI LD data and metadata considerations](#ngsi-ld-data-and-metadata-considerations) @@ -187,9 +188,9 @@ configured for a single device in the device provisioning, or it can be defined The entity type should be defined both in the group and in the device, but the entity name (entity ID) is not defined in the group. In that case, if there is no a existing device the same device ID, the entity name of the device generated -will be a concatenation of the entity type and the device ID (I.E: `entityType:device_id`). It is possible to define the -entity name as an expression, using the [Expression Language](#expression-language-support) through the `entityNameExp` -attribute in the group. +will be a concatenation of the entity type and the device ID (I.E: `entityType:device_id`). If you need to generate the +entity name differently, it is possible to define an expression to generate it, using the parameter `entityNameExp` in +the group as described in the [Entity Name expression support](#entity-name-expression-support) section. It is also possible to configure how each of the measures obtained from the device is mapped to different attributes. The name and type of the attribute is configured by the user (globally for all the devices in the group or in a per @@ -271,6 +272,59 @@ If for any reason you need the entity at CB before the first measure of the corr IOTAgent, you can create it in advance using the Context Broker [NGSI v2 API](https://github.com/telefonicaid/fiware-orion/blob/master/doc/manuals/orion-api.md). +## Entity Name expression support + +By default, the entity name used to persist the device measures in the Context Broker can be defined in the device +provisioning or, if the device is autoprovisioned, it is generated by the IoT Agent as a concatenation of the entity +type and the device ID. If you need to generate the entity name differently, it is possible to define an expression to +generate it, using the [Expression Language](#expression-language-support) through the `entityNameExp` attribute in the +group. + +With this feature, the entity name can be generated dynamically based not only on the device ID and entity type, but +also on the measures reported by the device or any other context information. The `entityNameExp` attribute is only +available at the group level. **Important**: when using `entityNameExp`, the `entity_name` attribute in the device +provisioning is ignored. This means that the entity name used to store the device information in the Context Broker is +always generated by the `entityNameExp` expression. If you need to explicitly define the entity name for a particular +device, you can include a particular condition in the `entityNameExp` expression to handle that case (e.g. +`id == 'myDevice' ? 'myEntity' : entityType + ':' + id`). + +The following example shows how to define an entity name expression: + +```json +{ + "services": [ + { + "resource": "/json", + "apikey": "801230BJKL23Y9090DSFL123HJK09H324HV8732", + "entity_type": "TemperatureSensor", + "entityNameExp": "id + '__' + sn", + "attributes": [ + { + "object_id": "t", + "name": "temperature", + "type": "Number" + }, + { + "object_id": "sn", + "name": "serialNumber", + "type": "Text" + } + ] + } + ] +} +``` + +As defined above, the `entityNameExp` is `id + '__' + sn` and it will generate the entity name by concatenating the +device ID and the serial number reported by the device. For example, for a given measure with `id` equal to `dev123` and +`sn` equal to `ABCDEF`, the resulting entity name will be `dev123__ABCDEF`. + +Note that, when using `entityNameExp`, the `entity_name` of the device provisioning is set to the result of the +expression the first time the device is created. If the expression is modified later, the `entity_name` of the device +provisioning will not be updated, but the value used to persist the device measures in the Context Broker will be the +result of the new expression. This can lead to a situation where the `entity_name` of the device provisioning and the +entity name used in the Context Broker are different. + ## Multientity support The IOTA is able to persists measures coming from a single device to more than one entity, declaring the target entities @@ -555,7 +609,8 @@ of expression in the IoT Agent are: - [Metadata](#expression-support-in-metadata) - Commands payload transformation (push and pull). - Auto provisioned devices entity name. It is configured at config Group level by setting the `entityNameExp` - parameter. It defines an expression to generate the Entity Name for autoprovisioned devices. + parameter. It defines an expression to generate the Entity Name for autoprovisioned devices. More information in the + [Entity Name expression support](#entity-name-expression-support) section. - Dynamic `endpoint` definition. Configured at device level, it defines where the device listen for push http commands. It can be either a static value or an expression. @@ -1715,7 +1770,7 @@ Config group is represented by a JSON object with the following fields: | `static_attributes` | ✓ | | | this attributes will be added to all the entities of this group 'as is', additional `metadata` is optional. | | `internal_attributes` | ✓ | | | optional section with free format, to allow specific IoT Agents to store information along with the devices in the Device Registry. | | `explicitAttrs` | ✓ | string or bool | ✓ | optional field to support selective ignore of measures so that IOTA doesn’t progress. See details in [specific section](#explicitly-defined-attributes-explicitattrs) | -| `entityNameExp` | ✓ | string | | optional field to allow use expressions to define entity name, instead default name, based on the device ID and the entity type (i.e. `:`) | +| `entityNameExp` | ✓ | string | | optional field to allow use expressions to define entity name, instead default name, based on the device ID and the entity type (i.e. `:`). More information in [specific section](#entity-name-expression-entitynameexp) | | `ngsiVersion` | ✓ | string | | optional string value used in mixed mode to switch between **NGSI-v2** and **NGSI-LD** payloads. Possible values are: `v2` or `ld`. The default is `v2`. When not running in mixed mode, this field is ignored. | | `defaultEntityNameConjunction` | ✓ | string | | optional string value to set default conjunction string used to compose a default `entity_name` when is not provided at device provisioning time. | | `autoprovision` | ✓ | bool | ✓? | optional boolean: If `false`, autoprovisioned devices (i.e. devices that are not created with an explicit provision operation but when the first measure arrives) are not allowed in this group. Default (in the case of omitting the field) is `true`. |