![\"GitHub\"](\"https://fiware.github.io/tutorials.Subscriptions/icon/GitHub-Mark-32px.png\"){kind=icon}
FIWARE 106: Subscribing to Changes in ContextThe tutorial builds on the entities and Stock Management Frontend\napplication created in the previous example to enable users to understand\nthe NGSI\nSubscribe/Notify paradigm and how to use NGSI subscriptions within their own code.
\nThe docker-compose file for this tutorial can be found on GitHub:
FIWARE 106: Subscribing to Changes in Context
\n\n\"Don't call us, we'll call you\"
\n— Dorothy Kilgallen (The Voice Of Broadway)
\n
Within the FIWARE platform, an entity represents the state of a physical or conceptural object which exists in the real world. \nEvery smart solution needs to know the current state of these object at any given moment in time.
\nThe context of each of these entities is constantly changing. For example, within the stock management example, the context will\nchange as new stores open up, products are sold, prices change and so on. For a smart solution based on IoT sensor data, this issue\nis even more pressing as the system will constantly be reacting to changes in the real world.
\nUntil now all the operations we have used to change the state of the system have been synchronous - changes have been made by \ndirectly by a user or application and they have been informed of the result. The Orion Context Broker offers also an asynchronous\nnotification mechanism - applications can subscribe to changes of context information so that they can\nbe informed when something happens. This means the application does not need to continously poll or repeat query requests.
\nUse of the subscription mechanism will therefore reduce both the volume of requests and amount of data being passed between components\nwithin the system. This reduction in network traffic will improve the overall responsiveness.
\nThe relationship between our entities is defined as shown:
\n![\"\"](\"https://fiware.github.io/tutorials.Subscriptions/img/entities.png\")
In the previous tutorial, a simple Node.js Express application was created.\nThis tutorial will use the monitor page to watch the status of recent requests, and a store page to buy products. Once the services\nare running these pages can be accessed from the following URLs:
\nThe event monitor can be found at: http://localhost:3000/app/monitor
![\"FIWARE](\"https://fiware.github.io/tutorials.Subscriptions/img/monitor.png\")
Store002 can be found at: http://localhost:3000/app/store/urn:ngsi-ld:Store:002
![\"Store\"](\"https://fiware.github.io/tutorials.Subscriptions/img/store2.png\")
This application will make use of only 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\npersistence of the context data it holds. To request context data from external sources, a simple Context Provider NGSI \nproxy has also been added. To visualise and interact with the Context we will add a simple Express application
\nTherefore, the architecture will consist of four elements:
\nSince all interactions between the elements are initiated by HTTP requests, the entities can be containerized and run\nfrom exposed ports.
\n![\"\"](\"https://fiware.github.io/tutorials.Subscriptions/img/architecture.png\")
The necessary configuration information can be seen in the services section of the associated docker-compose.yml file. It\nhas been described in a previous tutorial
To keep things simple both components will be run using Docker. Docker is a container technology\nwhich 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 sevices can be brought up in a single \ncommmand. 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
\nWe will start up our services using a simple bash script. Windows users should download cygwin to provide a\ncommand 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 create; ./services start;\nThis command will also import seed data from the previous Stock Management example on startup.
\n\n\n:information_source: Note: If you want to clean up and start over again you can do so with the following command:
\n\n./services stop\n
To follow the tutorial correctly please ensure you have the follow pages available on tabs in your browser before you enter any cUrl commands.
\nThe event monitor can be found at: http://localhost:3000/app/monitor
The stores can be found at:
\nhttp://localhost:3000/app/store/urn:ngsi-ld:Store:001http://localhost:3000/app/store/urn:ngsi-ld:Store:002Within the stock management example, imagine that the regional manager of the company wants to alter the price of a product. \nThe new price should immediately be reflected at the till in all stores within the system. It would be possible to set up the\nsystem so that it was constantly polling for new information, however prices are not changed very frequently so this would be\na waste of resources and create a lot of unnecessary data traffic.
\nThe alternative is to create a subscription which will POST a payload to a \"well-known\" URL whenever a price has changed. \nA new subscription can be added by making a POST request to the /v2/subscriptions/ endpoint as shown below:
curl --request POST \\\n --url 'http://localhost:1026/v2/subscriptions/' \\\n --header 'content-type: application/json' \\\n --data '{\n \"description\": \"Notify me of all product price changes\",\n \"subject\": {\n \"entities\": [{\"idPattern\": \".*\", \"type\": \"Product\"}],\n \"condition\": { \n \"attrs\": [ \"price\" ]\n }\n },\n \"notification\": {\n \"http\": {\n \"url\": \"http://context-provider:3000/subscription/price-change\"\n }\n }\n}'\nThe body of the POST request consists of two parts, the subject section of the request (consisting of entities and conditions)states that the subscription will be fired whenever the price attribute of any Product entity is altered. The notification section of the body states that once the conditions of the subscription have been met, a POST request containing all affected Product entities will be sent to the URL http://context-provider:3000/subscription/price-change which is handled by the stock management front-end application.
For a first run, when the subscription is created, the Orion Context Broker runs the condition test, and since it has not been run before makes the assumption that all products have been changed. Therefore a request is sent to subscription/price-change immediately as shown:
http://localhost:3000/app/monitor![\"\"](\"https://fiware.github.io/tutorials.Subscriptions/img/products-subscription.png\")
Code within the Stock Management Front-End application handles received the POST request as shown:
\nrouter.post('/subscription/:type', (req, res) => {\n _.forEach(req.body.data, item => {\n broadcastEvents(req, item, ['refStore', 'refProduct', 'refShelf', 'type']);\n });\n res.status(204).send();\n});\n\nfunction broadcastEvents(req, item, types) {\n const message = req.params.type + ' received';\n _.forEach(types, type => {\n if (item[type]) {\n req.app.get('io').emit(item[type], message);\n }\n });\n}\nThis business logic emits socket io events to any registered parties (such as the cash till)
\nThe cash till has been set to reload if is receives an event - however in this case the prices have not changed yet, so the product prices\nremain the same - for example a bottle of beer remains at 0.99€
\nhttp://localhost:3000/app/store/urn:ngsi-ld:Store:002![\"\"](\"https://fiware.github.io/tutorials.Subscriptions/img/beer-99.png\")
Let's reduce the price of a bottle of beer to 0.89€. This can't be done programmatically yet, so it has to be done with a curl command\nas shown:
\ncurl --request PUT \\\n --url 'http://localhost:1026/v2/entities/urn:ngsi-ld:Product:001/attrs/price/value' \\\n --header 'Content-Type: text/plain' \\\n --data 89\nWhenever an attribute of the Product entity is updated, the Orion Context Broker checks for any existing subscriptions \n(which exist for that entity) and applies the condition test. This time only one Product entity has changed since the last run therefore a POST request is sent to subscription/price-change - which only contains one Product in the body:
http://localhost:3000/app/monitor![\"\"](\"https://fiware.github.io/tutorials.Subscriptions/img/price-change.png\")
The business logic of the Stock Management Front End again emits socket io events to any registered parties (such as the cash till)\nand since the price has changed the till now displays a bottle of beer at 0.89€
\nhttp://localhost:3000/app/store/urn:ngsi-ld:Store:002![\"\"](\"https://fiware.github.io/tutorials.Subscriptions/img/beer-89.png\")
attrs and attrsFormatWith the previous example the full verbose data from each affected Product entity was sent with the POST notification.\nThis is not very efficient.
\nThe amount of data to passed can be reduced by adding an attrs attribute which will specify a list of attributes to be \nincluded in notification messages - other attributes are ignored
\n\nTip an
\nexceptAttrsattribute also exists to return all attributes except for those on the exclude list.\nattrsandexceptAttrscannot be used simualtaneously in the same subscription
The attrsFormat attribute specifies how the entities are represented in notifications. A verbose response is returned by \ndefault keyValues and values work in the same manner as a v2/entities GET request.
expressionLets create two more subscriptions which will only fire under specific conditions - and will only return key-value pairs for\nthe entity affected. Imagine that the warehouse of each store now wants to be informed whenever the amount of product on the \nshelf falls below a threshold level.
\nThe subscription is tested whenever the shelfCount of an InventoryItem is updated, however the addition of an expression \nattribute will mean that the subscription will only fire if the expression returns valid data - for example\n\"q\": \"shelfCount<10;refStore==urn:ngsi-ld:Store:001 tests that the shelfCount is below ten and that the item is in store 001.\nThis means that we can set up out business logic so that other stores wont be bothered by notifications.
The following command is a low stock notification for Store 001
\ncurl --request POST \\\n --url 'http://localhost:1026/v2/subscriptions' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"description\": \"Notify me of low stock in Store 001\",\n \"subject\": {\n \"entities\": [{\"idPattern\": \".*\",\"type\": \"InventoryItem\"}],\n \"condition\": {\n \"attrs\": [\"shelfCount\"],\n \"expression\": {\"q\": \"shelfCount<10;refStore==urn:ngsi-ld:Store:001\"}\n }\n },\n \"notification\": {\n \"http\": {\n \"url\": \"http://context-provider:3000/subscription/low-stock-store001\"\n },\n \"attrsFormat\" : \"keyValues\"\n }\n}'\nThe following command is a low stock notification for Store 002
\ncurl --request POST \\\n --url 'http://localhost:1026/v2/subscriptions' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"description\": \"Notify me of low stock in Store 002\",\n \"subject\": {\n \"entities\": [{\"idPattern\": \".*\", \"type\": \"InventoryItem\"}],\n \"condition\": {\n \"attrs\": [\"shelfCount\"],\n \"expression\": {\"q\": \"shelfCount<10;refStore==urn:ngsi-ld:Store:002\"}\n }\n },\n \"notification\": {\n \"http\": {\n \"url\": \"http://context-provider:3000/subscription/low-stock-store002\"\n },\n \"attrsFormat\" : \"keyValues\"\n }\n}'\nThe two requests are very similiar. It is merely the url and the expresssion attributes which differ. The first cUrl command\nwill only fire if the affected InventoryItem entity has a reference to Store 001 and the second one if the affected\nInventoryItem entity has a reference to Store 001. Obviously the URLs must be different so that the business logic of our\napplication is able to react diffferently to each request.
\n\nTip: You can set stock levels directly by making a PUT request as shown:
\n\ncurl --request PUT \\\n --url 'http://localhost:1026/v2/entities/urn:ngsi-ld:InventoryItem:005/attrs/shelfCount/value' \\\n --header 'Content-Type: text/plain' \\\n --data 5\n
If you now buy items from Store 002, once an InventoryItem dips below ten items the following occurs
\nhttp://localhost:3000/app/monitor![\"\"](\"https://fiware.github.io/tutorials.Subscriptions/img/low-stock-monitor.png\")
As you can see the key value pairs of the affected InventoryItem have been passed to the Stock Managment Front End.
\nIf you look at the store itself:
\nhttp://localhost:3000/app/store/urn:ngsi-ld:Store:002![\"\"](\"https://fiware.github.io/tutorials.Subscriptions/img/low-stock-warehouse.png\")
An alert has been raised by the business logic within the application.
\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[{"content":"Subscribing to Changes of State","slug":"subscribing-to-changes-of-state"},{"content":"Architecture","slug":"architecture"},{"content":"Prerequisites","slug":"prerequisites"},{"content":"Start Up","slug":"start-up"},{"content":"Using Subscriptions","slug":"using-subscriptions"}],"owner":"513743","collectionId":"b240d096-0af8-44c3-9a5e-22fee62f49e7","publishedId":"RW1dHeTR","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"4C4C4C","highlight":"233C68"},"publishDate":"2018-05-31T10:56:35.000Z"},"item":[{"name":"Subscription Actions","item":[{"name":"Create a Subscription (Product)","id":"bc935401-10bf-45d6-89aa-4dfd69e7fbdb","request":{"method":"POST","header":[{"key":"content-type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"description\": \"Notify me of all product price changes\",\n \"subject\": {\n \"entities\": [\n {\n \"idPattern\": \".*\", \"type\": \"Product\"\n }\n ],\n \"condition\": {\n \"attrs\": [ \"price\" ]\n }\n },\n \"notification\": {\n \"http\": {\n \"url\": \"http://context-provider:3000/subscription/price-change\"\n }\n }\n}"},"url":"http://localhost:1026/v2/subscriptions/","description":"This example creates a new subscription. The subscription will fire an asynchronous notification to a URL\nwhenever the context is changed and the conditions of the subscription - Any Changes to Product prices - are met.
\nNew subscriptions can be added by making a POST request to the /v2/subscriptions/ endpoint.
The subject section of the request states that the subscription will be fired whenever the price attribute of\nany Product entity is altered.
The notification section of the body states that a POST request containing all affected entities will\nbe sent to the http://context-provider:3000/subscription/price-change endpoint.
Subscription ids are auto-generated when the subscription is created and returned in the header of the response.
\nSubsequent requests will create duplicate subscriptions
\n","urlObject":{"protocol":"http","path":["v2","subscriptions",""],"host":["localhost:1026"],"query":[],"variable":[]}},"response":[],"_postman_id":"bc935401-10bf-45d6-89aa-4dfd69e7fbdb"},{"name":"Delete a Subscription","id":"e3292a9d-4405-4046-911c-fefbdb5fbd30","request":{"method":"DELETE","header":[],"body":{"mode":"raw","raw":""},"url":"http://localhost:1026:1026/v2/subscriptions/5c90c0c041df0cb69e62704c","description":"This example deletes the Subscription with id=5ae079b86e4f353c5163c939 from the context.
Subscriptions can be deleted by making a DELETE request to the /v2/subscriptions/<subscription-id> endpoint.
The Subscription id had been auto-generated when the subscription was created.
\nSubsequent requests using the same id will result in an error response since the subscription no longer exists
This example amends an existing subscription with the id 5ae07c7e6e4f353c5163c93e and updates the notification URL.
Subscriptions can be updated making a PATCH request to the /v2/subscriptions/<subscription-id> endpoint.
The Subscription id had been auto-generated when the subscription was created.
\n","urlObject":{"protocol":"http","port":"1026","path":["v2","subscriptions","5ae07c7e6e4f353c5163c93e"],"host":["{{host}}"],"query":[],"variable":[]}},"response":[],"_postman_id":"d1b01fe3-e61f-4111-8440-e594e1651096"},{"name":"List all Subscriptions","id":"9d2cda75-2cb7-4868-acf5-6ff8c7bb269e","request":{"method":"GET","header":[],"body":{"mode":"raw","raw":"{\n \"subject\": {\n \"entities\": [{\n \"id\": \"\" \n }],\n \"condition\": {\n \"attrs\": [\"capacity\"]\n }\n },\n \"notification\": {\n \"http\": {\n \"url\": \"http://localhost:8000\"\n }\n }\n}"},"url":"http://localhost:1026/v2/subscriptions/","description":"This example lists all subscriptions by making a GET request to the /v2/subscriptions/ endpoint.
The notification section of each subscription will also include the last time the conditios of the subscription\nwere met, and whether associated the POST action was successful.
This example obtains the full details of a subscription with a given id.
\nThe response includes additional details in the notification section showing \nthe last time the conditions of the subscription were met, and whether associated the POST \naction was successful.
Subscription details can be read by making a GET request to the /v2/subscriptions/<subscription-id> endpoint.
The Subscription id had been auto-generated when the subscription was created.
\n","urlObject":{"protocol":"http","path":["v2","subscriptions","5aead3361587e1918de90aba"],"host":["localhost:1026"],"query":[],"variable":[]}},"response":[],"_postman_id":"7f872cf8-e6a7-409b-97b3-a5d5ef689eb6"},{"name":"Create a Subscription ( Store 1) - Low Stock","id":"c4525080-603c-44ac-a1d7-b351e3101a36","request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"description\": \"Notify me of low stock in Store 001\",\n \"subject\": {\n \"entities\": [\n {\n \"idPattern\": \".*\",\n \"type\": \"InventoryItem\"\n }\n ],\n \"condition\": {\n \"attrs\": [\n \"shelfCount\"\n ],\n \"expression\": {\n \"q\": \"shelfCount<10;refStore==urn:ngsi-ld:Store:001\"\n }\n }\n },\n \"notification\": {\n \"http\": {\n \"url\": \"http://context-provider:3000/subscription/low-stock-store001\"\n },\n \"attrsFormat\" : \"keyValues\"\n }\n}"},"url":"http://localhost:1026/v2/subscriptions","description":"This example creates a new subscription which will only fire under specific conditions - \nlow stock for Store 001 - and will only return key-value pairs\nfor the entity affected. The subscription will fire an asynchronous notification to a URL\nwhenever the context is changed and only when all of the conditions of the subscription are met.
\nNew subscriptions can be added by making a POST request to the /v2/subscriptions/ endpoint.
subject section of the request states that the subscription will be checked whenever the shelfCount attribute of\nany InventoryItem entity is altered.expression section of the request states that the subscription will only fire if the shelfCount is below 10 items\nand the InventoryItem entity belongs to Store:001notification section of the body states that a POST request containing all affected entities will\nbe sent to the http://context-provider:3000/subscription/low-stock-store001 endpoint. . The attrsFormat attribute informs\nthe context broker to only send key-value pairsSubsequent requests will create duplicate subscriptions
\n","urlObject":{"protocol":"http","path":["v2","subscriptions"],"host":["localhost:1026"],"query":[],"variable":[]}},"response":[],"_postman_id":"c4525080-603c-44ac-a1d7-b351e3101a36"},{"name":"Create a Subscription ( Store 2) - Low Stock","id":"7a0f67d5-d975-4f9a-8c69-42eb850f4a1f","request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"description\": \"Notify me of low stock in Store 002\",\n \"subject\": {\n \"entities\": [\n {\n \"idPattern\": \".*\",\n \"type\": \"InventoryItem\"\n }\n ],\n \"condition\": {\n \"attrs\": [\n \"shelfCount\"\n ],\n \"expression\": {\n \"q\": \"shelfCount<10;refStore==urn:ngsi-ld:Store:002\"\n }\n }\n },\n \"notification\": {\n \"http\": {\n \"url\": \"http://context-provider:3000/subscription/low-stock-store002\"\n },\n \"attrsFormat\" : \"keyValues\"\n }\n}"},"url":"http://localhost:1026/v2/subscriptions","description":"This example creates a new subscription which will only fire under specific conditions - low stock for Store 002 - and will only return \nkey-value pairs for the entity affected. The subscription will fire an asynchronous notification to a URL\nwhenever the context is changed and only when all of the conditions of the subscription are met.
\nNew subscriptions can be added by making a POST request to the /v2/subscriptions/ endpoint.
subject section of the request states that the subscription will be checked whenever the shelfCount attribute of\nany InventoryItem entity is altered.expression section of the request states that the subscription will only fire if the shelfCount is below 10 items\nand the InventoryItem entity belongs to Store:002notification section of the body states that a POST request containing all affected entities will\nbe sent to the http://context-provider:3000/subscription/low-stock-store002 endpoint. The attrsFormat attribute informs\nthe context broker to only send key-value pairsSubsequent requests will create duplicate subscriptions
\n","urlObject":{"protocol":"http","path":["v2","subscriptions"],"host":["localhost:1026"],"query":[],"variable":[]}},"response":[],"_postman_id":"7a0f67d5-d975-4f9a-8c69-42eb850f4a1f"}],"id":"89da7ed6-4c05-4360-810b-a80e7ee213aa","description":"A subscription notifies another service by making a POST request to a specified URL when the conditions of the subscription have been met.
\nThe CRUD operations for subscriptions map on to the expected HTTP verbs under the /v2/subscriptions/ endpoint.
The <subscription-id> is auto generated when the subscription is created and returned in Header\nof the POST response to be used by the other operation thereafter.
This example reduces the price of a can of Beer to 0.89 €.
\nIt updates the value of the price attribute of the Entity with id=urn:ngsi-ld:Product:001
Exisiting attribute values can be altered by making a PUT request to the /v2/entities/<entity>/attrs/<attribute>/value endpoint.
This example reduces the number of beer cans left on sale in Checkpoint Markt\n(store:002) down to 5. If a subscription has been set up, a warning will be sent to the warehouse.
The value of the shelfCount attribute of the Entity with id=urn:ngsi-ld:InventoryItem:005can be \naltered by making a PUT request to the /v2/entities/<entity>/attrs/<attribute>/value endpoint.
The tutorial assumes that users will buy the products from the web app,\nhowever Postman commands are also provided for convenience.
\nhttp://localhost:3000/app/monitorhttp://localhost:3000/app/store/urn:ngsi-ld:Store:002