FIWARE Querying Time Series Data (Mongo-DB).postman_collection.json

{
	"info": {
		"_postman_id": "b5650122-d605-4517-ae17-fa21733d725d",
		"name": "FIWARE Querying Time Series Data (Mongo-DB)",
		"description": "This tutorial is an introduction to [FIWARE STH-Comet](https://fiware-sth-comet.readthedocs.io/) - a generic enabler which is used to retrieve trend data from a Mongo-DB database. The tutorial activates the IoT sensors connected in the [previous tutorial](https://github.com/Fiware/tutorials.IoT-Agent) and persists measurements from those sensors into a database and retrieves time-based aggregations of that data.\n\nThe `docker-compose` files for this tutorial can be found on GitHub: \n\n![GitHub](https://fiware.github.io/tutorials.Short-Term-History/icon/GitHub-Mark-32px.png) [FIWARE 303: Short Term Historic Data](https://github.com/Fiware/tutorials.Short-Term-History)\n\n# Querying Time Series Data\n\n> \"The *\"moment\"* has no yesterday or tomorrow. It is not the result of thought and therefore has no time.\"\n>\n> — Bruce Lee\n\n\nWithin the FIWARE platform, historical context data can be persisted to a database using a combination of the **Orion \nContext Broker** and the **Cygnus** generic enabler. This results in a series of data points being written to the\ndatabase of your choice. Each time-stamped data point represents the state of context entities at a given moment in time.\nThe individual data points are relatively meaningless on their own, it is only through combining a series data points\nthat meaningful statistics such as maxima, minima and trends can be observed.\n\nThe creation and analysis of trend data is a common requirement of context-driven systems - therefore the FIWARE platform \noffers a generic enabler ([STH-Comet](https://fiware-sth-comet.readthedocs.io/)) specifically to deal with the issue of persisting and interpreting time series data. **STH-Comet** itself can be used in two modes:\n\n* In *minimal* mode, **STH-Comet** is responsible for both data collection and interpreting the data when requested\n* In *formal* mode, the collection of data is delegated to **Cygnus**, **STH-Comet** merely reads from an existing database.\n\nOf the two modes of operation, the *formal* mode is more flexible, but *minimal* mode is simpler and easier to set-up. The key differences between the two are summarized in the table below:\n\n\n|                                                         | *minimal* mode                | *formal* mode              |\n|---------------------------------------------------------|-------------------------------|----------------------------|\n| Is the system easy to set-up  properly?                 | Only one configuration supported - Easy to set up                | Highly configurable - Complex to set up          |\n| Which component is responsible for a data persistance?  | **STH-Comet**                 | **Cygnus**                 |\n| What is the role of **STH-Comet**?                      | Reading and writing data      | Data Read only             |\n| What is the role of **Cygnus**?                         | Not Used                      | Data Write only            |\n| Where is the data aggregated?                           | Mongo-DB database connected to **STH-Comet** only| Mongo-DB database connected to both **Cygnus** and **STH-Comet** |\n| Can the system be configured to use other databases?    | No                            | Yes                        |\n| Does the solution scale easily?                         | Does not scale easily - use for simple systems | Scales easily - use for complex systems |\n| Can the system cope with high rates of throughput?      | No - use where throughput is low | Yes - use where throughput is high |\n\n\n## Analyzing time series data\n\nThe appropriate use of time series data analysis will depend on your use case and the reliability of the data measurements you receive. Time series data analysis can be used to answer questions such as:\n\n* What was the maximum measurement of a device within a given time period?\n* What was the average measurement of a device within a given time period?\n* What was the sum of the measurements sent by a device within a given time period?\n\nIt can also be used to reduce the signficance of each individual data point to exclude outliers by smoothing.\n\n\n\n#### Device Monitor\n\nFor the purpose of this tutorial, a series of dummy IoT devices have been created, which will be attached to the context broker. Details of the architecture and protocol used can be found in the [IoT Sensors tutorial](https://github.com/Fiware/tutorials.IoT-Sensors).\nThe state of each device can be seen on the UltraLight device monitor web-page found at: `http://localhost:3000/device/monitor`\n\n![FIWARE Monitor](https://fiware.github.io/tutorials.Short-Term-History/img/device-monitor.png)\n\n\n\n# Architecture\n\nThis application builds on the components and dummy IoT devices created in \n[previous tutorials](https://github.com/Fiware/tutorials.IoT-Agent/). It will use three or four FIWARE components depending on the configuration of the system:\nthe [Orion Context Broker](https://fiware-orion.readthedocs.io/en/latest/), the\n[IoT Agent for Ultralight 2.0](http://fiware-iotagent-ul.readthedocs.io/en/latest/),\n[STH-Comet](http://fiware-cygnus.readthedocs.io/en/latest/) and\n[Cygnus](http://fiware-cygnus.readthedocs.io/en/latest/). \n\nTherefore the overall architecture will consist of the following elements:\n\n* Four **FIWARE Generic Enablers**:\n  * The FIWARE [Orion Context Broker](https://fiware-orion.readthedocs.io/en/latest/) which will receive requests using [NGSI](https://fiware.github.io/specifications/OpenAPI/ngsiv2)\n  * The FIWARE [IoT Agent for Ultralight 2.0](http://fiware-iotagent-ul.readthedocs.io/en/latest/) which will receive northbound measurements from the dummy IoT devices in [Ultralight 2.0](http://fiware-iotagent-ul.readthedocs.io/en/latest/usermanual/index.html#user-programmers-manual) format and convert them to [NGSI](https://fiware.github.io/specifications/OpenAPI/ngsiv2) requests for the context broker to alter the state of the context entities\n  * FIWARE [STH-Comet](http://fiware-sth-comet.readthedocs.io/) will:\n    + interpret time-based data queries\n    + subscribe to context changes and persist them into a **Mongo-DB** database  (*minimal* mode only)\n   * FIWARE [Cygnus](http://fiware-cygnus.readthedocs.io/en/latest/) where it will subscribe to context changes and persist them into a **Mongo-DB** database (*formal* mode only) \n\n> :information_source: **Note:** **Cygnus** will only be used if **STH-Comet** is configured in *formal* mode.\n\n* A [MongoDB](https://www.mongodb.com/) database:\n  * Used by the **Orion Context Broker** to hold context data information such as data entities, subscriptions and registrations\n  * Used by the **IoT Agent** to hold device information such as device URLs and Keys\n  * Used as a data sink to hold time-based historical context data\n     + In *minimal* mode - this is read and populated by **STH-Comet** \n     + In *formal* mode - this is populated by **Cygnus**  and read by **STH-Comet** \n* Three **Context Providers**:\n  * The **Stock Management Frontend** is not used in this tutorial. It does the following:\n    + Display store information and allow users to interact with the dummy IoT devices\n    + Show which products can be bought at each store\n    + Allow users to \"buy\" products and reduce the stock count.\n  * A webserver acting as set of [dummy IoT devices](https://github.com/Fiware/tutorials.IoT-Sensors) using the [Ultralight 2.0](http://fiware-iotagent-ul.readthedocs.io/en/latest/usermanual/index.html#user-programmers-manual) protocol running over HTTP.\n  * The **Context Provider NGSI** proxy is not used in this tutorial. It does the following:\n    + receive requests using [NGSI](https://fiware.github.io/specifications/OpenAPI/ngsiv2)\n    + makes requests to publicly available data sources using their own APIs in a proprietary format \n    + returns context data back to the Orion Context Broker in [NGSI](https://fiware.github.io/specifications/OpenAPI/ngsiv2) format.\n\n\n\n\nSince all interactions between the elements are initiated by HTTP requests, the entities can be containerized and run from exposed ports. \n\nThe specific architecture of both the *minimal* and *formal* configurations is discussed below.\n\n\n\n# Prerequisites\n\n## Docker and Docker Compose \n\nTo keep things simple all components will be run using [Docker](https://www.docker.com). **Docker** is a container technology which allows to different components isolated into their respective environments. \n\n* To install Docker on Windows follow the instructions [here](https://docs.docker.com/docker-for-windows/)\n* To install Docker on Mac follow the instructions [here](https://docs.docker.com/docker-for-mac/)\n* To install Docker on Linux follow the instructions [here](https://docs.docker.com/install/)\n\n**Docker Compose** is a tool for defining and running multi-container Docker applications. A  series of [YAML files](https://raw.githubusercontent.com/Fiware/tutorials.Historic-Context/master/cygnus) are used configure the required\nservices for the application. This means all container services can be brought up in a single command. 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](https://docs.docker.com/compose/install/)\n\n## Cygwin for Windows\n\nWe will start up our services using a simple Bash script. Windows users should download [cygwin](http://www.cygwin.com/) to provide a command line functionality similar to a Linux distribution on Windows.\n\n\n\n\n# Start Up\n\nBefore you start you should ensure that you have obtained or built the necessary Docker images locally. Please run\n\n```console\n./services create\n``` \n\n>**Note** The `context-provider` image has not yet been pushed to Docker hub.\n> Failing to build the Docker sources before proceeding will result in the following error:\n>\n>```\n>Pulling context-provider (fiware/cp-web-app:latest)...\n>ERROR: The image for the service you're trying to recreate has been removed.\n>```\n\n\nThereafter, all services can be initialized from the command line by running the [services](https://github.com/Fiware/tutorials.Historic-Context/blob/master/services) Bash script provided within the repository:\n\n```console\n./services <command>\n``` \n\nWhere `<command>` will vary depending upon the mode we wish to activate.\nThis command will also import seed data from the previous tutorials and provision the dummy IoT sensors on startup.\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>```console\n>./services stop\n>``` \n>",
		"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
	},
	"item": [
		{
			"name": "Minimal Mode (STH-Comet only) ",
			"item": [
				{
					"name": "STH-Comet - Obtain version information",
					"request": {
						"method": "GET",
						"header": [],
						"url": {
							"raw": "http://{{sth-comet}}/version",
							"protocol": "http",
							"host": [
								"{{sth-comet}}"
							],
							"path": [
								"version"
							]
						},
						"description": "Once STH-Comet is running, You can check the status by making an HTTP request to the exposed `STH_PORT` port. \nIf the response is blank, this is usually because STH-Comet is not running or is listening on another port.\n\n>**Troubleshooting:** What if the response is blank ?\n>\n> * To check that a docker container is running try\n>\n>```bash\n>docker ps\n>```\n>\n>You should see several containers running. If `sth-comet` is not running, you can restart the containers as necessary."
					},
					"response": []
				},
				{
					"name": "Orion - STH-Comet - Aggregate Motion Sensor Count Events",
					"request": {
						"method": "POST",
						"header": [
							{
								"key": "Content-Type",
								"value": "application/json"
							},
							{
								"key": "fiware-service",
								"value": "openiot"
							},
							{
								"key": "fiware-servicepath",
								"value": "/"
							}
						],
						"body": {
							"mode": "raw",
							"raw": "{\n  \"description\": \"Notify STH-Comet of all Motion Sensor count changes\",\n  \"subject\": {\n    \"entities\": [\n      {\n        \"idPattern\": \"Motion.*\"\n      }\n    ],\n    \"condition\": {\n      \"attrs\": [\n        \"count\"\n      ]\n    }\n  },\n  \"notification\": {\n    \"http\": {\n      \"url\": \"http://sth-comet:8666/notify\"\n    },\n    \"attrs\": [\n      \"count\"\n    ],\n    \"attrsFormat\": \"legacy\"\n  }\n}"
						},
						"url": {
							"raw": "http://{{orion}}/v2/subscriptions/",
							"protocol": "http",
							"host": [
								"{{orion}}"
							],
							"path": [
								"v2",
								"subscriptions",
								""
							]
						},
						"description": "Once a dynamic context system is up and running, we need to inform **STH-Comet** directly of changes in context.\nThe rate of change of the **Motion Sensor** is driven by events in the real-world. We need to receive\nevery event to be able to aggregate the results.\n\nThis is done by making a POST request to the `/v2/subscription` endpoint of the Orion Context Broker.\n\n* The `fiware-service` and `fiware-servicepath` headers are used to filter the subscription to only listen to measurements from the attached IoT Sensors\n* The `idPattern` in the request body ensures that **STH-Comet** will be informed of all **Motion Sensor** data changes.\n* The notification `url` must match the configured `STH_PORT`\n* The `attrsFormat=legacy` is required since **STH-Comet** currently only accepts notifications in the older NGSI v1 format."
					},
					"response": []
				},
				{
					"name": "Orion - STH-Comet - Sample Lamp Luminosity",
					"request": {
						"method": "POST",
						"header": [
							{
								"key": "Content-Type",
								"value": "application/json"
							},
							{
								"key": "fiware-service",
								"value": "openiot"
							},
							{
								"key": "fiware-servicepath",
								"value": "/"
							}
						],
						"body": {
							"mode": "raw",
							"raw": "{\n  \"description\": \"Notify STH-Comet to sample Lamp changes every five seconds\",\n  \"subject\": {\n    \"entities\": [\n      {\n        \"idPattern\": \"Lamp.*\"\n      }\n    ],\n    \"condition\": {\n      \"attrs\": [\n        \"luminosity\"\n      ]\n    }\n  },\n  \"notification\": {\n    \"http\": {\n      \"url\": \"http://sth-comet:8666/notify\"\n    },\n    \"attrs\": [\n      \"luminosity\"\n    ],\n    \"attrsFormat\": \"legacy\"\n  },\n  \"throttling\": 5\n}"
						},
						"url": {
							"raw": "http://{{orion}}/v2/subscriptions/",
							"protocol": "http",
							"host": [
								"{{orion}}"
							],
							"path": [
								"v2",
								"subscriptions",
								""
							]
						},
						"description": "Once a dynamic context system is up and running, we need to inform **STH-Comet** directly of changes in context.\n\nThe luminosity of the **Smart Lamp** is constantly changing, we only need to **sample** the values to be\nable to work out relevant statistics such as minimum and maximum values and rates of change.\n\nThis is done by making a POST request to the `/v2/subscription` endpoint of the Orion Context Broker\nand including the `throttling` attribute in the request body.\n\n* The `fiware-service` and `fiware-servicepath` headers are used to filter the subscription to only listen to measurements from the attached IoT Sensors\n* The `idPattern` in the request body ensures that **STH-Comet** will be informed of all **Smart Lamp** data changes only\n* The notification `url` must match the configured `STH_PORT`\n* The `attrsFormat=legacy` is required since **STH-Comet** currently only accepts notifications in the older NGSI v1 format.\n* The `throttling` value defines the rate that changes are sampled."
					},
					"response": []
				},
				{
					"name": "Orion - STH-Comet Check Subscriptions are working",
					"request": {
						"method": "GET",
						"header": [
							{
								"key": "fiware-service",
								"value": "openiot"
							},
							{
								"key": "fiware-servicepath",
								"value": "/"
							}
						],
						"url": {
							"raw": "http://{{orion}}/v2/subscriptions/",
							"protocol": "http",
							"host": [
								"{{orion}}"
							],
							"path": [
								"v2",
								"subscriptions",
								""
							]
						},
						"description": "If the subscription have been created, you can check to see if they are firing by making a GET \nrequest to the `/v2/subscriptions` endpoint.\n\nWithin the `notification` section of the response, you can see several additional `attributes` which describe the health of the subscription\n\nIf the criteria of the subscription have been met, `timesSent` should be greater than `0`.\nA zero value would indicate that the `subject` of the subscription is incorrect or the subscription \nhas created with the wrong `fiware-service-path` or `fiware-service` header\n\nThe `lastNotification` should be a recent timestamp - if this is not the case, then the devices\nare not regularly sending data. Remember to unlock the **Smart Door** and switch on the **Smart Lamp**\n\nThe `lastSuccess` should match the `lastNotification` date - if this is not the case \nthen **STH-Comet** is not receiving the subscription properly. Check that the host name\nand port are correct. \n\nFinally, check that the `status` of the subscription is `active` - an expired subscription\nwill not fire."
					},
					"response": []
				}
			],
			"description": "In the *minimal* configuration, **STH-Comet** is used to persisting historic context data and also used to make time-based queries.\nAll operations take place on the same port `8666`. The MongoDB instance listening on the standard\n`27017` port is used to hold data the historic context data as well as holding data related to the **Orion Context Broker** and the **IoT Agent**.\nThe overall architecture can be seen below:\n\n![](https://fiware.github.io/tutorials.Short-Term-History/img/sth-comet.png)\n\n## Database Server Configuration\n\n```yaml\n  mongo-db:\n    image: mongo:3.6\n    hostname: mongo-db\n    container_name: db-mongo\n    ports:\n        - \"27017:27017\"\n    networks:\n        - default\n    command: --bind_ip_all --smallfiles\n```\n\n## STH-Comet Configuration \n\n```yaml\n  sth-comet:\n    image: fiware/sth-comet\n    hostname: sth-comet\n    container_name: fiware-sth-comet\n    depends_on:\n        - mongo-db\n    networks:\n        - default\n    ports:\n        - \"8666:8666\"\n    environment:\n        - STH_HOST=0.0.0.0\n        - STH_PORT=8666\n        - DB_PREFIX=sth_\n        - DB_URI=mongo-db:27017\n        - LOGOPS_LEVEL=DEBUG\n```\n\nThe `sth-comet` container is listening on one port: \n\n* The Operations for port for STH-Comet - `8666` is where the service will be listening for notifications from the Orion context broker as well\n  as time based query requests from cUrl or Postman\n\nThe `sth-comet` container is driven by environment variables as shown:\n\n| Key        |Value            |Description|\n|------------|-----------------|-----------|\n|STH_HOST    |`0.0.0.0`        | The address where STH-Comet is hosted - within this container it means all IPv4 addresses on the local machine  |\n|STH_PORT    |`8666`           | Operations Port that STH-Comet listens on, it is also used when subscribing to context data changes |\n|DB_PREFIX   |`sth_`           | The prefix added to each database entity if none is provided |\n|DB_URI      |`mongo-db:27017` | The  Mongo-DB server which STH-Comet will contact to persist historical context data |\n|LOGOPS_LEVEL|`DEBUG`          | The logging level for STH-Comet |\n\n\n## *minimal* configuration - Start up\n\nTo start the system using the *minimal* configuration using **STH-Comet**  only, run the following command:\n\n```console\n./services sth-comet\n``` \n\n",
			"event": [
				{
					"listen": "prerequest",
					"script": {
						"id": "a63e990e-c30a-419c-a54c-5d24baa792f2",
						"type": "text/javascript",
						"exec": [
							""
						]
					}
				},
				{
					"listen": "test",
					"script": {
						"id": "d2710f35-1e52-4ac5-87ad-d7a93c640386",
						"type": "text/javascript",
						"exec": [
							""
						]
					}
				}
			]
		},
		{
			"name": "Formal Mode (Cygnus + STH-Comet)",
			"item": [
				{
					"name": "Cygnus - Obtain version information",
					"request": {
						"method": "GET",
						"header": [],
						"url": {
							"raw": "http://{{cygnus}}/v1/version",
							"protocol": "http",
							"host": [
								"{{cygnus}}"
							],
							"path": [
								"v1",
								"version"
							]
						},
						"description": "Once Cygnus is running, You can check the status by making an HTTP request to the exposed `CYGNUS_API_PORT` port. \nIf the response is blank, this is usually because Cygnus is not running or is listening on another port.\n\n>**Troubleshooting:** What if the response is blank ?\n>\n> * To check that a docker container is running try\n>\n>```bash\n>docker ps\n>```\n>\n>You should see several containers running. If `cygnus` is not running, you can restart the containers as necessary."
					},
					"response": []
				},
				{
					"name": "STH-Comet - Obtain version information",
					"request": {
						"method": "GET",
						"header": [],
						"url": {
							"raw": "http://{{sth-comet}}/version",
							"protocol": "http",
							"host": [
								"{{sth-comet}}"
							],
							"path": [
								"version"
							]
						},
						"description": "Once STH-Comet is running, You can check the status by making an HTTP request to the exposed `STH_PORT` port. \nIf the response is blank, this is usually because STH-Comet is not running or is listening on another port.\n\n>**Troubleshooting:** What if the response is blank ?\n>\n> * To check that a docker container is running try\n>\n>```bash\n>docker ps\n>```\n>\n>You should see several containers running. If `sth-comet` is not running, you can restart the containers as necessary."
					},
					"response": []
				},
				{
					"name": "Orion - Cygnus - Aggregate Motion Sensor Count Events",
					"request": {
						"method": "POST",
						"header": [
							{
								"key": "Content-Type",
								"value": "application/json"
							},
							{
								"key": "fiware-service",
								"value": "openiot"
							},
							{
								"key": "fiware-servicepath",
								"value": "/"
							}
						],
						"body": {
							"mode": "raw",
							"raw": "{\n  \"description\": \"Notify Cygnus of all Motion Sensor count changes\",\n  \"subject\": {\n    \"entities\": [\n      {\n        \"idPattern\": \"Motion.*\"\n      }\n    ],\n    \"condition\": {\n      \"attrs\": [\n        \"count\"\n      ]\n    }\n  },\n  \"notification\": {\n    \"http\": {\n      \"url\": \"http://cygnus:5051/notify\"\n    },\n    \"attrs\": [\n      \"count\"\n    ]\n  }\n}"
						},
						"url": {
							"raw": "http://{{orion}}/v2/subscriptions/",
							"protocol": "http",
							"host": [
								"{{orion}}"
							],
							"path": [
								"v2",
								"subscriptions",
								""
							]
						},
						"description": "Once a dynamic context system is up and running, we need to inform **Cygnus** of changes in context.\n**Cygnus** will store the historical context data in a Mongo-DB database and **STH-Comet** will only\nbe used to read the persisted data.\n\n\nThe rate of change of the **Motion Sensor** is driven by events in the real-world. We need to receive\nevery event to be able to aggregate the results.\n\nThis is done by making a POST request to the `/v2/subscription` endpoint of the **Orion Context Broker**.\n\n* The `fiware-service` and `fiware-servicepath` headers are used to filter the subscription to only listen to measurements from the attached IoT Sensors\n* The `idPattern` in the request body ensures that **Cygnus**  will be informed of all **Motion Sensor** data changes.\n* The notification `url` must match the configured `CYGNUS_MONGO_SERVICE_PORT`"
					},
					"response": []
				},
				{
					"name": "Orion - Cygnus - Sample Lamp Luminosity",
					"request": {
						"method": "POST",
						"header": [
							{
								"key": "Content-Type",
								"value": "application/json"
							},
							{
								"key": "fiware-service",
								"value": "openiot"
							},
							{
								"key": "fiware-servicepath",
								"value": "/"
							}
						],
						"body": {
							"mode": "raw",
							"raw": "{\n  \"description\": \"Notify Cygnus to sample Lamp changes every five seconds\",\n  \"subject\": {\n    \"entities\": [\n      {\n        \"idPattern\": \"Lamp.*\"\n      }\n    ],\n    \"condition\": {\n      \"attrs\": [\n        \"luminosity\"\n      ]\n    }\n  },\n  \"notification\": {\n    \"http\": {\n      \"url\": \"http://cygnus:5051/notify\"\n    },\n    \"attrs\": [\n      \"luminosity\"\n    ]\n  },\n  \"throttling\": 5\n}"
						},
						"url": {
							"raw": "http://{{orion}}/v2/subscriptions/",
							"protocol": "http",
							"host": [
								"{{orion}}"
							],
							"path": [
								"v2",
								"subscriptions",
								""
							]
						},
						"description": "Once a dynamic context system is up and running, we need to inform **Cygnus** of changes in context.\n**Cygnus** will store the historical context data in a Mongo-DB database and **STH-Comet** will only\nbe used to read the persisted data.\n\nThe luminosity of the **Smart Lamp** is constantly changing, we only need to **sample** the values to be\nable to work out relevant statistics such as minimum and maximum values and rates of change.\n\nThis is done by making a POST request to the `/v2/subscription` endpoint of the **Orion Context Broker**\nand including the `throttling` attribute in the request body.\n\n* The `fiware-service` and `fiware-servicepath` headers are used to filter the subscription to only listen to measurements from the attached IoT Sensors\n* The `idPattern` in the request body ensures that **Cygnus** will be informed of all **Smart Lamp** data changes only\n* The notification `url` must match the configured `CYGNUS_MONGO_SERVICE_PORT`\n* The `throttling` value defines the rate that changes are sampled."
					},
					"response": []
				},
				{
					"name": "Orion - Cygnus - Check Subscriptions are working",
					"request": {
						"method": "GET",
						"header": [
							{
								"key": "fiware-service",
								"value": "openiot"
							},
							{
								"key": "fiware-servicepath",
								"value": "/"
							}
						],
						"url": {
							"raw": "http://{{orion}}/v2/subscriptions/",
							"protocol": "http",
							"host": [
								"{{orion}}"
							],
							"path": [
								"v2",
								"subscriptions",
								""
							]
						},
						"description": "If the subscriptions have been created, you can check to see if they is firing by making a GET \nrequest to the `/v2/subscriptions` endpoint.\n\nWithin the `notification` section of the response, you can see several additional `attributes` which describe the health of the subscription\n\nIf the criteria of the subscription have been met, `timesSent` should be greater than `0`.\nA zero value would indicate that the `subject` of the subscription is incorrect or the subscription \nhas created with the wrong `fiware-service-path` or `fiware-service` header\n\nThe `lastNotification` should be a recent timestamp - if this is not the case, then the devices\nare not regularly sending data. Remember to unlock the **Smart Door** and switch on the **Smart Lamp**\n\nThe `lastSuccess` should match the `lastNotification` date - if this is not the case \nthen **Cygnus** is not receiving the subscription properly. Check that the host name\nand port are correct. \n\nFinally, check that the `status` of the subscription is `active` - an expired subscription\nwill not fire."
					},
					"response": []
				}
			],
			"description": "The *formal* configuration is uses **Cygnus** to persist historic context data into a MongoDB database in the same manner as had been presented in the\n[previous tutorial](https://github.com/Fiware/tutorials.Historic-Context). The existing MongoDB instance (listening on the standard\n`27017` port) is used to hold data related to the **Orion Context Broker**, the **IoT Agent** and the historic\ncontext data persisted by **Cygnus**. **STH-Comet** is also attached to the same database to read data from it. The overall architecture can be seen below:\n\n![](https://fiware.github.io/tutorials.Short-Term-History/img/cygnus-sth-comet.png)\n\n## Database Server Configuration\n\n```yaml\n  mongo-db:\n    image: mongo:3.6\n    hostname: mongo-db\n    container_name: db-mongo\n    ports:\n        - \"27017:27017\"\n    networks:\n        - default\n    command: --bind_ip_all --smallfiles\n```\n\n## STH-Comet Configuration \n\n```yaml\n  sth-comet:\n    image: fiware/sth-comet\n    hostname: sth-comet\n    container_name: fiware-sth-comet\n    depends_on:\n        - mongo-db\n    networks:\n        - default\n    ports:\n        - \"8666:8666\"\n    environment:\n        - STH_HOST=0.0.0.0\n        - STH_PORT=8666\n        - DB_PREFIX=sth_\n        - DB_URI=mongo-db:27017\n        - LOGOPS_LEVEL=DEBUG\n```\n\n## Cygnus Configuration \n\n```yaml\n  cygnus:\n    image: fiware/cygnus-ngsi:latest\n    hostname: cygnus\n    container_name: fiware-cygnus\n    depends_on:\n        - mongo-db\n    networks:\n        - default\n    expose:\n        - \"5080\"\n    ports:\n        - \"5050:5050\"\n        - \"5080:5080\"\n    environment:\n        - \"CYGNUS_MONGO_HOSTS=mongo-db:27017\"\n        - \"CYGNUS_LOG_LEVEL=DEBUG\"\n        - \"CYGNUS_SERVICE_PORT=5050\"\n        - \"CYGNUS_API_PORT=5080\"\n```\n\nThe `sth-comet` container is listening on one port: \n\n* The Operations for port for STH-Comet - `8666` is where the service will be listening for time based query requests from cUrl or Postman\n\nThe `sth-comet` container is driven by environment variables as shown:\n\n| Key        |Value            |Description|\n|------------|-----------------|-----------|\n|STH_HOST    |`0.0.0.0`        | The address where STH-Comet is hosted - within this container it means all IPv4 addresses on the local machine  |\n|STH_PORT    |`8666`           | Operations Port that STH-Comet listens on |\n|DB_PREFIX   |`sth_`           | The prefix added to each database entity if none is provided |\n|DB_URI      |`mongo-db:27017` | The  Mongo-DB server which STH-Comet will contact to persist historical context data |\n|LOGOPS_LEVEL|`DEBUG`          | The logging level for STH-Comet |\n\nThe `cygnus` container is listening on two ports: \n\n* The Subscription Port for Cygnus - `5050` is where the service will be listening for notifications from the Orion context broker\n* The Management Port for Cygnus - `5080` is exposed purely for tutorial access - so that cUrl or Postman can make provisioning commands\n  without being part of the same network.\n\n\nThe `cygnus` container is driven by environment variables as shown:\n\n| Key                           |Value         |Description|\n|-------------------------------|--------------|-----------|\n|CYGNUS_MONGO_HOSTS         |`mongo-db:27017`  | Comma separated list of Mongo-DB servers which Cygnus will contact to persist historical context data |\n|CYGNUS_LOG_LEVEL               |`DEBUG`       | The logging level for Cygnus |\n|CYGNUS_SERVICE_PORT            |`5050`        | Notification Port that Cygnus listens when subscribing to context data changes|\n|CYGNUS_API_PORT                |`5080`        | Port that Cygnus listens on for operational reasons |\n\n\n\n## *formal* configuration - Start up\n\nTo start the system using the *formal* configuration using **Cygnus**  and **STH-Comet**, run the following command:\n\n```console\n./services cygnus\n``` \n",
			"event": [
				{
					"listen": "prerequest",
					"script": {
						"id": "f8ca5d71-4eb4-42b9-95e0-c3ef11567514",
						"type": "text/javascript",
						"exec": [
							""
						]
					}
				},
				{
					"listen": "test",
					"script": {
						"id": "43d701ab-eb41-472e-875e-4ac51e27579a",
						"type": "text/javascript",
						"exec": [
							""
						]
					}
				}
			]
		},
		{
			"name": "Time Series Data Queries",
			"item": [
				{
					"name": "List  the first N Sampled Values",
					"request": {
						"method": "GET",
						"header": [
							{
								"key": "Content-Type",
								"value": "application/json",
								"disabled": true
							},
							{
								"key": "fiware-service",
								"value": "openiot"
							},
							{
								"key": "fiware-servicepath",
								"value": "/"
							}
						],
						"url": {
							"raw": "http://{{sth-comet}}/STH/v1/contextEntities/type/Lamp/id/Lamp:001/attributes/luminosity?hLimit=3&hOffset=0",
							"protocol": "http",
							"host": [
								"{{sth-comet}}"
							],
							"path": [
								"STH",
								"v1",
								"contextEntities",
								"type",
								"Lamp",
								"id",
								"Lamp:001",
								"attributes",
								"luminosity"
							],
							"query": [
								{
									"key": "hLimit",
									"value": "3",
									"description": "The number of entries per page."
								},
								{
									"key": "hOffset",
									"value": "0",
									"description": "The pagination offset"
								}
							]
						},
						"description": "This example shows the first 3 sampled `luminosity` values from `Lamp:001`. \n\nTo obtain the short term history of a context entity attribute, send a GET request to\n`../STH/v1/contextEntities/type/<Entity>/id/<entity-id>/attributes/<attribute>`\n\nthe `hLimit` parameter restricts the result to N values. `hOffset=0` will start with the first value."
					},
					"response": []
				},
				{
					"name": "List N Sampled Values at an Offset",
					"request": {
						"method": "GET",
						"header": [
							{
								"key": "Content-Type",
								"value": "application/json",
								"disabled": true
							},
							{
								"key": "fiware-service",
								"value": "openiot"
							},
							{
								"key": "fiware-servicepath",
								"value": "/"
							}
						],
						"url": {
							"raw": "http://{{sth-comet}}/STH/v1/contextEntities/type/Motion/id/Motion:001/attributes/count?hLimit=3&hOffset=3",
							"protocol": "http",
							"host": [
								"{{sth-comet}}"
							],
							"path": [
								"STH",
								"v1",
								"contextEntities",
								"type",
								"Motion",
								"id",
								"Motion:001",
								"attributes",
								"count"
							],
							"query": [
								{
									"key": "hLimit",
									"value": "3",
									"description": "The number of entries per page."
								},
								{
									"key": "hOffset",
									"value": "3",
									"description": "The pagination offset"
								}
							]
						},
						"description": "This example shows the fourth, fifth and sixth sampled `count` values from `Motion:001`. \n\nTo obtain the short term history of a context entity attribute, send a GET request to\n`../STH/v1/contextEntities/type/<Entity>/id/<entity-id>/attributes/<attribute>`\n\nthe `hLimit` parameter restricts the result to N values. \nSetting `hOffset` to a non-zero value will start from the Nth measurement"
					},
					"response": []
				},
				{
					"name": "List the latest N sampled Values",
					"request": {
						"method": "GET",
						"header": [
							{
								"key": "Content-Type",
								"value": "application/json",
								"disabled": true
							},
							{
								"key": "fiware-service",
								"value": "openiot"
							},
							{
								"key": "fiware-servicepath",
								"value": "/"
							}
						],
						"url": {
							"raw": "http://{{sth-comet}}/STH/v1/contextEntities/type/Motion/id/Motion:001/attributes/count?lastN=3",
							"protocol": "http",
							"host": [
								"{{sth-comet}}"
							],
							"path": [
								"STH",
								"v1",
								"contextEntities",
								"type",
								"Motion",
								"id",
								"Motion:001",
								"attributes",
								"count"
							],
							"query": [
								{
									"key": "lastN",
									"value": "3",
									"description": "The number of entries to return"
								}
							]
						},
						"description": "This example shows latest three sampled `count` values from `Motion:001`. \n\nTo obtain the short term history of a context entity attribute, send a GET request to\n`../STH/v1/contextEntities/type/<Entity>/id/<entity-id>/attributes/<attribute>`\n\nif the `lastN` parameter is set, the result will return the N latest measurements only."
					},
					"response": []
				},
				{
					"name": "List the Sum of Values over a time period",
					"request": {
						"method": "GET",
						"header": [
							{
								"key": "Content-Type",
								"value": "application/json",
								"disabled": true
							},
							{
								"key": "fiware-service",
								"value": "openiot"
							},
							{
								"key": "fiware-servicepath",
								"value": "/"
							}
						],
						"url": {
							"raw": "http://{{sth-comet}}/STH/v1/contextEntities/type/Motion/id/Motion:001/attributes/count?aggrMethod=sum&aggrPeriod=minute",
							"protocol": "http",
							"host": [
								"{{sth-comet}}"
							],
							"path": [
								"STH",
								"v1",
								"contextEntities",
								"type",
								"Motion",
								"id",
								"Motion:001",
								"attributes",
								"count"
							],
							"query": [
								{
									"key": "aggrMethod",
									"value": "sum"
								},
								{
									"key": "aggrPeriod",
									"value": "minute"
								},
								{
									"key": "dateFrom",
									"value": null,
									"description": "The starting date and time",
									"disabled": true
								},
								{
									"key": "dateTo",
									"value": null,
									"description": "The final date and time",
									"disabled": true
								}
							]
						},
						"description": "This example shows total `count` values from `Motion:001` over each minute\n\nTo obtain the short term history of a context entity attribute, send a GET request to\n`../STH/v1/contextEntities/type/<Entity>/id/<entity-id>/attributes/<attribute>`\n\nThe `aggrMethod` parameter determines the type of aggregation to perform over the time series, \nthe `aggrPeriod` is one of `second`, `minute`, `hour` or `day`. \n\nAlways select the most appropiate time period based on the frequency of your data collection.\n`minute` has been selected because the `Motion:001` is firing a few times within each minute."
					},
					"response": []
				},
				{
					"name": "List the Minimum Values over a time period",
					"request": {
						"method": "GET",
						"header": [
							{
								"key": "Content-Type",
								"value": "application/json",
								"disabled": true
							},
							{
								"key": "fiware-service",
								"value": "openiot"
							},
							{
								"key": "fiware-servicepath",
								"value": "/"
							}
						],
						"url": {
							"raw": "http://{{sth-comet}}/STH/v1/contextEntities/type/Lamp/id/Lamp:001/attributes/luminosity?aggrMethod=min&aggrPeriod=minute",
							"protocol": "http",
							"host": [
								"{{sth-comet}}"
							],
							"path": [
								"STH",
								"v1",
								"contextEntities",
								"type",
								"Lamp",
								"id",
								"Lamp:001",
								"attributes",
								"luminosity"
							],
							"query": [
								{
									"key": "aggrMethod",
									"value": "min"
								},
								{
									"key": "aggrPeriod",
									"value": "minute"
								},
								{
									"key": "dateFrom",
									"value": "2018-01-01T00:00:00.000Z",
									"description": "The starting date and time",
									"disabled": true
								},
								{
									"key": "dateTo",
									"value": "2019-12-31T00:00:00.000Z",
									"description": "The final date and time",
									"disabled": true
								}
							]
						},
						"description": "This example shows minimum `luminosity` values from `Lamp:001` over each minute\n\nTo obtain the short term history of a context entity attribute, send a GET request to\n`../STH/v1/contextEntities/type/<Entity>/id/<entity-id>/attributes/<attribute>`\n\nThe `aggrMethod` parameter determines the type of aggregation to perform over the time series, \nthe `aggrPeriod` is one of `second`, `minute`, `hour` or `day`. \n\nThe luminocity of the **Smart Lamp** is continually changing and therefore tracking the minimum value makes sense.\nThe **Motion Sensor** is not suitable for this as it only offers binary values."
					},
					"response": []
				},
				{
					"name": "List the Maximum Values over a time period",
					"request": {
						"method": "GET",
						"header": [
							{
								"key": "Content-Type",
								"value": "application/json",
								"disabled": true
							},
							{
								"key": "fiware-service",
								"value": "openiot"
							},
							{
								"key": "fiware-servicepath",
								"value": "/"
							}
						],
						"url": {
							"raw": "http://{{sth-comet}}/STH/v1/contextEntities/type/Lamp/id/Lamp:001/attributes/luminosity?aggrMethod=max&aggrPeriod=minute",
							"protocol": "http",
							"host": [
								"{{sth-comet}}"
							],
							"path": [
								"STH",
								"v1",
								"contextEntities",
								"type",
								"Lamp",
								"id",
								"Lamp:001",
								"attributes",
								"luminosity"
							],
							"query": [
								{
									"key": "aggrMethod",
									"value": "max"
								},
								{
									"key": "aggrPeriod",
									"value": "minute"
								},
								{
									"key": "dateFrom",
									"value": null,
									"description": "The starting date and time",
									"disabled": true
								},
								{
									"key": "dateTo",
									"value": null,
									"description": "The final date and time",
									"disabled": true
								}
							]
						},
						"description": "This example shows maximum `luminosity` values from `Lamp:001` over each minute\n\nTo obtain the short term history of a context entity attribute, send a GET request to\n`../STH/v1/contextEntities/type/<Entity>/id/<entity-id>/attributes/<attribute>`\n\nThe `aggrMethod` parameter determines the type of aggregation to perform over the time series, \nthe `aggrPeriod` is one of `second`, `minute`, `hour` or `day`."
					},
					"response": []
				},
				{
					"name": "List Average Values over a time period",
					"request": {
						"method": "GET",
						"header": [
							{
								"key": "Content-Type",
								"value": "application/json",
								"disabled": true
							},
							{
								"key": "fiware-service",
								"value": "openiot"
							},
							{
								"key": "fiware-servicepath",
								"value": "/"
							}
						],
						"url": {
							"raw": "http://{{sth-comet}}/STH/v1/contextEntities/type/Lamp/id/Lamp:001/attributes/luminosity?aggrMethod=sum&aggrPeriod=minute",
							"protocol": "http",
							"host": [
								"{{sth-comet}}"
							],
							"path": [
								"STH",
								"v1",
								"contextEntities",
								"type",
								"Lamp",
								"id",
								"Lamp:001",
								"attributes",
								"luminosity"
							],
							"query": [
								{
									"key": "aggrMethod",
									"value": "sum"
								},
								{
									"key": "aggrPeriod",
									"value": "minute"
								},
								{
									"key": "dateFrom",
									"value": null,
									"description": "The starting date and time",
									"disabled": true
								},
								{
									"key": "dateTo",
									"value": null,
									"description": "The final date and time",
									"disabled": true
								}
							]
						},
						"description": "Querying for the mean value within a time period is not directly supported.\nThis example shows sum of `luminosity` values from `Lamp:001` over each minute.\nWhen combined with the number of samples the within the time period an average can be calculated from the data.\n\nTo obtain the short term history of a context entity attribute, send a GET request to\n`../STH/v1/contextEntities/type/<Entity>/id/<entity-id>/attributes/<attribute>`\n\nThe `aggrMethod` parameter determines the type of aggregation to perform over the time series, \nthe `aggrPeriod` is one of `second`, `minute`, `hour` or `day`."
					},
					"response": []
				}
			],
			"description": "The queries in this section assume you have already connected **STH-Comet** using either *minimal* mode or *formal* mode and have collected some data.",
			"event": [
				{
					"listen": "prerequest",
					"script": {
						"id": "9e70a754-3893-4617-adc7-c0471f7372f7",
						"type": "text/javascript",
						"exec": [
							""
						]
					}
				},
				{
					"listen": "test",
					"script": {
						"id": "c43d1162-ac29-4852-9094-b1b86604352b",
						"type": "text/javascript",
						"exec": [
							""
						]
					}
				}
			]
		}
	],
	"event": [
		{
			"listen": "prerequest",
			"script": {
				"id": "d1cff9ac-8932-417c-b6e2-582ba712ff79",
				"type": "text/javascript",
				"exec": [
					""
				]
			}
		},
		{
			"listen": "test",
			"script": {
				"id": "cc3f098c-a786-4112-a15e-b1c8c83cc657",
				"type": "text/javascript",
				"exec": [
					""
				]
			}
		}
	],
	"variable": [
		{
			"id": "a76b4b24-84ab-48bc-a2ca-4607b6e61068",
			"key": "orion",
			"value": "localhost:1026",
			"type": "string"
		},
		{
			"id": "d7d2c017-8dfe-4d8e-aaa7-584bcd9faaa3",
			"key": "cygnus",
			"value": "localhost:5080",
			"type": "string"
		},
		{
			"id": "1ad78e02-2af7-4340-a44c-cbbf3d57cff9",
			"key": "sth-comet",
			"value": "localhost:8666",
			"type": "string"
		}
	]
}