![\"GitHub\"](\"https://fiware.github.io/tutorials.Entity-Relationships/icon/GitHub-Mark-32px.png\"){kind=icon}
FIWARE 102: Batch Commands and Entity RelationshipsThis tutorial builds on the data created in the previous store finder example and creates and associates a series of related data entities to create a simple stock management system.
\nThe docker-compose file for this tutorial can be found on GitHub:
FIWARE 102: Batch Commands and Entity Relationships
Within the FIWARE platform, an entity represents the state of a physical or conceptural object which exists in the real world.
\nFor a simple stock management system, we will only need four types of entity. The relationship between our entities is defined as shown:
\n![\"\"](\"https://fiware.github.io/tutorials.Entity-Relationships/img/entities.png\")
As you can see, each of the entities defined above contain some properties which are liable to change. A product could change its price, stock could be sold and the shelf count of stock could be reduced and so on.
\nThis application will only make use of one FIWARE component - the Orion Context Broker. Usage of the Orion Context Broker is sufficient for an application to qualify as “Powered by FIWARE”.
\nCurrently, the Orion Context Broker relies on open source MongoDB technology to keep persistence of the context data it holds. Therefore, the architecture will consist of two elements:
\nSince all interactions between the two elements are initiated by HTTP requests, the entities can be containerized and run from exposed ports.
\n![\"\"](\"https://fiware.github.io/tutorials.Entity-Relationships/img/architecture.png\")
The necessary configuration information can be seen in the services section of the associated docker-compose.yml file:
orion:\n image: fiware/orion:latest\n hostname: orion\n container_name: orion\n depends_on:\n - context-db\n networks:\n - default\n expose:\n - \"1026\"\n ports:\n - \"1026:1026\"\n command: -dbhost context-db -logLevel DEBUG\n context-db:\n image: mongo:3.6\n hostname: context-db\n container_name: context-db\n expose:\n - \"27017\"\n ports:\n - \"27017:27017\"\n networks:\n - default\n command: --bind_ip_all --smallfiles\nBoth containers are residing on the same network - the Orion Context Broker is listening on Port 1026 \nand MongoDB is listening on the default port 271071. Both containers are also exposing the same ports\nexternally - this is purely for the tutorial access - so that cUrl or Postman can access them without\nbeing part of the same network. The command line initialization should be self explanatory.
To keep things simple both components will be run using Docker. Docker is a container technology which allows to different components isolated into their respective environments.
\nDocker Compose is a tool for defining and running multi-container Docker applications. A YAML file is used configure the required\nservices for the application. This means all container sevices can be brought up in a single commmand. Docker Compose is installed by default as part of Docker for Windows and Docker for Mac, however Linux users will need to follow the instructions found here
\nWe will start up our services using a simple bash script. Windows users should download cygwin to provide a command line functionality similar to a Linux distribution on Windows.
\nAll services can be initialised from the command line by running the bash script provided within the repository:
\n./services start\nThis example uses the convenience batch processing endpoint to re-create the two Store entities from the previous tutorial.
\nBatch processing uses the /v2/op/update endpoint with a payload with two attributes - actionType=APPEND means we will overwrite existing entities if they exist whereas the entities attribute holds an array of entities we wish to update.
As you can see each Store entity in the payload has been given a unique id (according to the NGSI-LD draft recommendation) and assigned type=Store.
This example uses the convenience batch processing endpoint to create a series of available products.
\nBatch processing uses the /v2/op/update endpoint with a payload with two attributes - actionType=APPEND means we will overwrite existing entities if they exist whereas the entities attribute holds an array of entities we wish to update.
Each product has a unique id following the NGSI-LD draft recommendation and has been assigned type=Product.
This example uses the convenience batch processing endpoint to create the five shelf entities.
\nBatch processing uses the /v2/op/update endpoint with a payload with two attributes - actionType=APPEND means we will overwrite existing entities if they exist whereas the entities attribute holds an array of entities we wish to update.
To differenciate Shelf Entities from Store Entities, each shelf has been assigned type=Shelf. The id of each Shelf Entity follows the NGSI-LD draft recommendation and is therefore unique.
Real-world properties such as name and location have been addded as properties to each shelf.
This example returns the context data of the Shelf entity with the id=urn:ngsi-ld:Shelf:unit001.
There are currently three additional property attributes present location, maxCapacity and name
Entity type
\n","type":"text/plain"},"key":"type","value":"Shelf"},{"description":{"content":"keyValues option in order to get a more compact and brief representation, including just attribute valuesvalues option combined with a list of attribute values attrs for an ordered list of attributes onlyThis example uses batch processing to amend the existing the Shelf entities to add a refStore relationship to each shelf. According to the FIWARE Data Modelling Guidelines on linked data, when an entity attribute is used as a link to other entities it should be named with the prefix ref plus the name of the target (linked) entity type.
Batch processing uses the /v2/op/update endpoint with a payload with two attributes - actionType=APPEND means we will overwrite existing entities if they exist whereas the entities attribute holds an array of entities we wish to update.
The value corresponds to a URN associated to an existing Store entity within the context.
\n","urlObject":{"protocol":"http","path":["v2","op","update"],"host":["localhost:1026"],"query":[],"variable":[]}},"response":[],"_postman_id":"d65c3b44-38b6-40ae-9b25-0fd208785b7e"},{"name":"Obtain Updated Shelf Information","id":"4010848f-f739-4d07-8870-700ce2641477","request":{"method":"GET","header":[],"body":{"mode":"raw","raw":""},"url":"http://localhost:1026/v2/entities/urn:ngsi-ld:Shelf:unit001/?options=keyValues","description":"This example returns the context data of the Shelf entity with the id=urn:ngsi-ld:Shelf:unit001.
The response now includes a new relationship property refStore, which has been added in the previous step.
Entity type
\n","type":"text/plain"},"key":"type","value":"Shelf"},{"description":{"content":"keyValues option in order to get a more compact and brief representation, including just attribute valuesvalues option combined with a list of attribute values attrs for an ordered list of attributes onlyThis example returns the refStore value associated with a given Shelf unit.
If the id and type of a data entity are known, a specific field can be requested by combining the options=values parameter and the attrs parameter.
The URN returned has a standard format: urn:ngsi-ld:<entity-type>:<entity-id>, which has been used as the id of the Store entity itself (based on the NGSI-LD draft recommendation), therefore it is a simple matter to request more information about the linked store by making a query to the /entities endpoint.
http://localhost:1026/v2/entities/urn:ngsi-ld:Store:001?options=keyValues\nEntity type
\n","type":"text/plain"},"key":"type","value":"Shelf"},{"description":{"content":"keyValues option in order to get a more compact and brief representation, including just attribute valuesvalues option combined with a list of attribute values attrs for an ordered list of attributes onlyOrdered list of attribute names to display
\n","type":"text/plain"},"key":"attrs","value":"refStore"}],"variable":[]}},"response":[],"_postman_id":"e808d05c-9e42-4429-b8da-bc1c35e230c5"},{"name":"Obtain all Shelf Units found within a Store","id":"4495d116-6f78-4b7d-bb5d-3e34059e16c8","request":{"method":"GET","header":[],"body":{"mode":"raw","raw":""},"url":"http://localhost:1026/v2/entities/?q=refStore==urn:ngsi-ld:Store:001&type=Shelf&options=values&attrs=name","description":"This example returns the name of all Shelf entities associated with the shop1.
The value of the query parameter q holds a URN of the form urn:ngsi-ld:<entity-type>:<entity-id> which corresponds to the the Relationship URN in order to filter the information returned.
Entity type
\n","type":"text/plain"},"key":"type","value":"Shelf"},{"description":{"content":"keyValues option in order to get a more compact and brief representation, including just attribute valuesvalues option combined with a list of attribute values attrs for an ordered list of attributes onlyOrdered list of attribute names to display
\n","type":"text/plain"},"key":"attrs","value":"name"}],"variable":[]}},"response":[],"_postman_id":"4495d116-6f78-4b7d-bb5d-3e34059e16c8"},{"name":"Putting a Product onto a shelf","id":"a0246746-38d8-4794-91e0-9a9d7a7acf34","request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"id\": \"urn:ngsi-ld:InventoryItem:001\", \"type\": \"InventoryItem\",\n \"refStore\": { \n \"type\": \"Relationship\",\n \"value\": \"urn:ngsi-ld:Store:001\"\n },\n \"refShelf\": { \n \"type\": \"Relationship\",\n \"value\": \"urn:ngsi-ld:Shelf:unit001\"\n },\n \"refProduct\": { \n \"type\": \"Relationship\",\n \"value\": \"urn:ngsi-ld:Product:001\"\n },\n \"stockCount\":{\n \"type\":\"Integer\", \"value\": 10000\n },\n \"shelfCount\":{\n \"type\":\"Integer\", \"value\": 50\n }\n}"},"url":"http://localhost:1026/v2/entities/","description":"The InventoryItem entity exists to associate data from other entities. It has a foreign key relationship to the Store, Shelf and Product entities and therefore requires relationship attributes called refStore, refShelf and refProduct.
Assigning a product to a shelf is simply a create an entity holding the relationship information and any other additional properties (such as stockCount and shelfCount).
This example returns the URN of all stores in which the product id=urn:ngsi-ld:Product:001 is sold. The URN returned has a standard format: urn:ngsi-ld:<entity-type>:<entity-id>.
Because we have based the id of the Store entity on the NGSI-LD draft recommendation), therefore it is a simple matter to request more information about the linked store by making a query to the /entities endpoint.
http://localhost:1026/v2/entities/urn:ngsi-ld:Store:001?options=keyValues\nSince there is no direct relationship between product and store, a query must be made to find all entities which have both refProduct and refStore attributes.
In our current context the type parameter is optional since only one type of entity contains the fields requested in the request
keyValues option in order to get a more compact and brief representation, including just attribute valuesvalues option combined with a list of attribute values attrs for an ordered list of attributes onlyOrdered list of attribute names to display
\n","type":"text/plain"},"key":"attrs","value":"refStore"},{"description":{"content":"Entity type
\n","type":"text/plain"},"key":"type","value":"InventoryItem"}],"variable":[]}},"response":[],"_postman_id":"c6995610-613a-4ec7-a39d-13fc922d7b6e"},{"name":"Find all Entities related to a Store","id":"8395a892-e980-44d0-8848-d2245cdf8c1c","request":{"method":"GET","header":[],"body":{"mode":"raw","raw":"{\n \"actionType\": \"APPEND\",\n \"entities\": [\n {\n \"id\": \"7770\",\n \"type\": \"Shelf\",\n \"store\": { \n \"type\": \"Relationship\",\n \"value\": \"urn:ngsi-ld:Store:store1\"\n },\n \"location\": {\n \"type\": \"geo:json\",\n \"value\": {\n \"type\": \"Point\",\n \"coordinates\": [13.3986112, 52.554699]\n }\n },\n \"name\": {\n \"type\": \"Text\",\n \"value\": \"Corner Unit\"\n },\n \"maxCapacity\": {\n \"type\": \"Integer\",\n \"value\": 50\n }\n},\n\n {\n \"id\": \"7771\",\n \"type\": \"Shelf\",\n \"store\": {\n \"type\": \"Relationship\",\n \"value\": \"urn:ngsi-ld:Store:store1\"\n },\n \"location\": {\n \"type\": \"geo:json\",\n \"value\": {\n \"type\": \"Point\",\n \"coordinates\": [\n 13.3987221,\n 52.5546640\n ]\n }\n },\n \"name\": {\n \"type\": \"Text\",\n \"value\": \"Wall Unit 1\"\n },\n \"maxCapacity\": {\n \"type\": \"Integer\",\n \"value\": 100\n }\n },\n \n {\n \"id\": \"7772\",\n \"type\": \"Shelf\",\n \"store\": {\n \"type\": \"Relationship\",\n \"value\": \"urn:ngsi-ld:Store:store1\"\n },\n \"location\": {\n \"type\": \"geo:json\",\n \"value\": {\n \"type\": \"Point\",\n \"coordinates\": [\n 13.3987221,\n 52.5546640\n ]\n }\n },\n \"name\": {\n \"type\": \"Text\",\n \"value\": \"Wall Unit 2\"\n },\n \"maxCapacity\": {\n \"type\": \"Integer\",\n \"value\": 100\n }\n }\n \n \n\n\n\n\n ]\n}"},"url":"http://localhost:1026/v2/entities/?q=refStore==urn:ngsi-ld:Store:001&options=count&attrs=type","description":"This example returns the key of all entities directly associated with the urn:ngsi-ld:Store:001.
The response lists a series of Shelf and InventoryItem entities - there are no products since there is no direct relationship between product and store.
\nIf this request returns an empty array, the entity has no associates.
\n","urlObject":{"protocol":"http","path":["v2","entities",""],"host":["localhost:1026"],"query":[{"key":"q","value":"refStore==urn:ngsi-ld:Store:001"},{"description":{"content":"keyValues option in order to get a more compact and brief representation, including just attribute valuesvalues option combined with a list of attribute values attrs for an ordered list of attributes onlyOrdered list of attribute names to display
\n","type":"text/plain"},"key":"attrs","value":"type"}],"variable":[]}},"response":[],"_postman_id":"8395a892-e980-44d0-8848-d2245cdf8c1c"}],"event":[{"listen":"prerequest","script":{"id":"f1d42f27-1cae-4144-b06e-237fad09b51b","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"028325fa-d62b-4d7a-afbf-5b138040015a","type":"text/javascript","exec":[""]}}],"variable":[{"id":"73b7c194-97af-4388-81ee-6dce0839c507","key":"orion","value":"localhost:1026","type":"string"}]}