![\"GitHub\"](\"https://fiware.github.io/tutorials.Entity-Relationships/icon/GitHub-Mark-32px.png\"){kind=icon}
FIWARE 102: Batch Commands and Entity RelationshipsThis tutorial teaches NGSI-LD users about batch commands and entity relationships. The tutorial builds on the data\ncreated in the previous Smart Farm example and\ncreates and associates a series of related data entities to create add sensors and farm workers to the farm.
\nThe docker-compose file for this tutorial can be found on GitHub:
FIWARE 102: Batch Commands and Entity Relationships
This tutorial teaches NGSI-LD users about batch commands and entity relationships. The tutorial builds on the data\ncreated in the previous Smart Farm example and\ncreates and associates a series of related data entities to create add sensors and farm workers to the farm.
\nWithin the FIWARE platform, the context of an entity represents the state of a physical or conceptual object which\nexists in the real world.
\nTo illustrate entity relationships within an FMIS system based on NGSI-LD, we will need to create a series of entities.\nFor this simplified FMIS, we will only need a small number entities. The relationship between our entities is defined as\nshown:
\n![\"\"](\"https://fiware.github.io/tutorials.Entity-Relationships/img/ngsi-ld-entities.png\")
As you can see, each of the entities defined above contain a mixture of static and dynamic data. Some properties are\nliable to change. A Herbicide could change its formula, hay could be sold and the fillingLevel of the barn could\nbe reduced and so on.
\n\nNote this tutorial uses the following typographic styling :
\n\n
\n- Entity types have been made bold text
\n- Data attributes are written in
\nmonospace text- Items in the real world use plain text
\nTherefore a person in the real world is represented in the context data by a Person entity, and a real world barn\nowned by a person is represented in the context data by a Building entity which has a
\nownerattribute.
The demo FMIS application will send and receive NGSI-LD calls to a compliant context broker. Since the standardized\nNGSI-LD interface is available across multiple context brokers, so we only need to pick one - for example the\nOrion Context Broker. The application will therefore only make use of\none FIWARE component.
\nCurrently, the Orion Context Broker relies on open source MongoDB technology to keep\npersistence of the context data it holds.
\nTo promote interoperability of data exchange, NGSI-LD context brokers explicitly expose a\nJSON-LD @context file to define the data held within the\ncontext entities. This defines a unique URI for every entity type and every attribute so that other services outside of\nthe NGSI domain are able to pick and choose the names of their data structures. Every @context file must be available\non the network. In our case the tutorial application will be used to host a series of static files.
Therefore, the architecture will consist of three elements:
\n@context files defining the context entities within the system.Since all interactions between the two elements are initiated by HTTP requests, the entities can be containerized and\nrun from exposed ports.
\n![\"\"](\"https://fiware.github.io/tutorials.Entity-Relationships/img/architecture-ld.png\")
The necessary configuration information can be seen in the services section of the associated docker-compose.yml file.\nIt has been described in a previous tutorial
To keep things simple both components will be run using Docker. Docker is a container\ntechnology which allows to different components isolated into their respective environments.
\nDocker Compose is a tool for defining and running multi-container Docker applications. A\nYAML file is used\nconfigure the required services for the application. This means all container services can be brought up in a single\ncommand. Docker Compose is installed by default as part of Docker for Windows and Docker for Mac, however Linux users\nwill need to follow the instructions found here
\nYou can check your current Docker and Docker Compose versions using the following commands:
\ndocker-compose -v\ndocker version\nPlease ensure that you are using Docker version 18.03 or higher and Docker Compose 1.21 or higher and upgrade if\nnecessary.
\nWe will start up our services using a simple Bash script. Windows users should download cygwin\nto provide a command-line functionality similar to a Linux distribution on Windows.
\nAll services can be initialised from the command-line by running the\nservices Bash script provided within\nthe repository. Please clone the repository and create the necessary images by running the commands as shown:
\ngit clone https://github.com/FIWARE/tutorials.Entity-Relationships.git\ncd tutorials.Entity-Relationships\ngit checkout NGSI-LD\n\n./services start\nThis command will also import seed data (Building, Person, TemperatureSensor, FillingLevelSensor,\nHerbicide and PartField) on startup.
\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[{"content":"Understanding Entities and Relationships","slug":"understanding-entities-and-relationships"},{"content":"Architecture","slug":"architecture"},{"content":"Prerequisites","slug":"prerequisites"},{"content":"Start Up","slug":"start-up"}],"owner":"513743","collectionId":"c1f2ca70-0f08-4466-bb27-117eadbb7efa","publishedId":"TVepAoFN","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"233C68"},"publishDate":"2020-11-16T14:50:35.000Z"},"item":[{"name":"Create Three Temperature Sensors","id":"96d317ad-849a-4dea-afed-c07600669122","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Link","value":"In the previous tutorial, we created each entity individually,
\nLets create several sensors at the same time. This request uses the convenience batch processing endpoint to create five\nentities. Batch processing uses the /ngsi-ld/v1/entityOperations/endpoints and the upsert endpoints means we will\ncreate new entities if they are not present and overwrite existing entities if they exist.
To differentiate different Device, each temperature sensor has been assigned type=TemperatureSensor. Real-world\nproperties such as category have been added as properties to each device.
Similarly, we can create a series of FillingLevelSensors entities by using the type=FillingLevelSensor.
In both cases we have encoded each entity id according to the NGSI-LD\nspecification - the proposal\nis that each id is a URN follows a standard format: urn:ngsi-ld:<entity-type>:<entity-id>. This will mean that every\nid in the system will be unique.
Device information can be requested by making a GET request on the /ngsi-ld/v1/entities endpoint. For example to\nreturn the context data of the devices.
As you can see there are currently three additional property attributes present description, category and\ncontrolledProperty
In databases, foreign keys are often used to designate a one-to-many relationship - for example a building can hold many\ndevices. In order to remember this information we need to add an association relationship similar to a foreign key.\nBatch processing can again be used to amend the existing the TemperatureSensor and FillingLevelSensor entities\nto add a controllingAsset attribute holding the relationship to each building controlled by the device. According to\nthe Smart Data Model Device\ndefinition https://uri.fiware.org/ns/data-models#controllingAsset is the URI long name to be used for this\nrelationship, and the value of the controllingAsset attribute corresponds to a URN associated to a Building entity\nitself.
The URN follows a standard format: urn:ngsi-ld:<entity-type>:<entity-id>.
The following request associates six devices to urn:ngsi-ld:Building:farm001, urn:ngsi-ld:Building:barn002 and\nurn:ngsi-ld:Building:farm002.
Now when the devcie information is requested again, the response has changed and includes a new property\ncontrollingAsset, which has been added in the previous step.
Entity type
\n","type":"text/plain"},"key":"type","value":"Shelf"}],"variable":[]}},"response":[],"_postman_id":"fea82e93-6022-4884-ae53-1970e83db681"},{"name":"Obtain a Foreign Key URN","id":"deee7416-9521-45ae-b718-71dc931211ca","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Link","value":"We can also make a request to retrieve the controllingAsset attribute relationship information from a known Device\nentity by using the options=keyValues setting.
This can be interpreted as \"I am making sensor readings inside the Building entity with the\nid=urn:ngsi-ld:Building:farm001\"
Entity type
\n","type":"text/plain"},"key":"type","value":"Shelf"},{"key":"attrs","value":"controllingAsset"}],"variable":[]}},"response":[],"_postman_id":"deee7416-9521-45ae-b718-71dc931211ca"},{"name":"Reading from Parent Entity to Child Entity","id":"a6953855-c9e1-4b81-a209-3ae1e70dc318","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Link","value":"Reading from a parent to a child can be done using the following query.
\nThis request is asking for the id of all Device entities associated to the URN urn:ngsi-ld:Building:farm001, the\nresponse is a JSON array as shown.
In plain English, this can be interpreted as \"There are two devices in urn:ngsi-ld:Building:farm001\". The request can\nbe altered use the count=true to return the number of entities which fulfill the criteria.
This returns an HTTP Header as part of the response which indicates the number of affected entities.
\n","urlObject":{"protocol":"http","path":["ngsi-ld","v1","entities"],"host":["localhost:1026"],"query":[{"key":"q","value":"controllingAsset==\"urn:ngsi-ld:Building:farm001\""},{"key":"options","value":"keyValues"},{"key":"attrs","value":"controllingAsset"}],"variable":[]}},"response":[],"_postman_id":"a6953855-c9e1-4b81-a209-3ae1e70dc318"},{"name":"Creating many-to-many Relationships","id":"40f3c039-6491-4342-9d4e-54da11585a5b","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Link","value":"Bridge Tables are often used to relate many-to-many relationships. For example, every spraying activity within the FMIS\nwill need to associate a farm worker, a product to apply, and a location to apply the treatment (known as a\nPartField)
\nIn order to hold the context information to \"direct a worker to spray a herbicide onto a field\" we will need to create a\nnew data entity Task which exists to associate data from other entities. It has a foreign key relationship to the\nPerson, Herbicide and PartField entities and therefore requires relationship attributes called field,\nherbicide and worker.
Assigning a task is simply done by creating an entity holding the relationship information and any other additional\nproperties (such as description and status)
When reading from a bridge table entity, the type of the entity must be known.
After creating at least one Task entity we can query Which workers are assigned activities in field\nurn:ngsi-ld:PartField:002? by making the following request:
Similarly we can request Which fields are treated using urn:ngsi-ld:Herbicide:001? by altering the request as shown:
Properties-of-Properties and Relationships of Properties are metadata. The addition of metadata entities such as\nthese into the context data allows users to navigate the graph of entities relationships and gain further insights about\nthe state of the system.
\nThe temperature readings from a temperature sensor have already been discussed. It may also be necessary to duplicate\nthis data into another entity. For example, the temperature reading of a sensor in the barn is also the temperature\nreading of the barn itself. A dummy reading has already been added into the urn:ngsi-ld:Building:farm001 Entity and\ncan be retrieved with a GET request.
As you can see the temperature Property holds additional information regarding the provider of the measurement, this\nwill allow additional inferences to be made.