Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add entityNameExp section into doc #1663

Merged
merged 1 commit into from
Oct 16, 2024
Merged

Add entityNameExp section into doc #1663

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
65 changes: 60 additions & 5 deletions doc/api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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. `<device_id>:<entity_type>`) |
| `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. `<device_id>:<entity_type>`). 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`. |
Expand Down
Loading