Version: v5.0

Named Telemetry Collections

Note: The nsfilter (namespace filter) query parameter is mandatory for every request. It sets the context, helping you look up resources within that namespace. Example: GET /itemsvc/api/v1/nameduseritems?nsfilter=proj_DrZrSNrW

Create Named Telemetry Collections#

Endpoints#

POST /itemsvc/api/v1/nameduseritems

Parameters#

Query#

Parameter	Type	Description	Required
`transactional`	Boolean	Set to true to make the request transactional.	Optional
`nsfilter`	String	namespace context	Required

Request#

Request body#

Parameter	Type	Description	Required
`_name`	String	Readable long-form name	Required
`_shortName`	String	An abbreviated name up to 22 characters that is used for reference	Required
`_description`	String	Describes the purpose of the NamedTelemetryCollection	Required
`_namespaces`	String	An array of namespaces you want to add the NamedTelemetryCollection to	Required
`_userType`	String	A user-defined type for the NamedTelemetryCollection that you can use to distinguish or group it by.	Required
`_itemClass`	String	Enter `"NamedTelemetryCollection"`.	Required
`_tsProperties`	Object	Pass an object with `_granularity` and `_expiry` properties.	Optional
`_tsProperties._granularity`	String	Enter one of the following options: `"seconds"`, `"minutes"`, `"hours"`. The default is `"minutes"`. The granularity defines the closest match to the time span between consecutive incoming measurements. If you ingest data from a given sensor once every 5 minutes, enter `"minutes"`.	Optional
`_tsProperties._expiry`	String	Enter an expiry time in seconds to automatically delete added readings after.	Optional

Expiry#

_expiry doesn't guarantee that expired data deletes immediately upon expiration. It is also controlled by_granularity as in below table. Data expire only when _ts crossed both covered time span and _expiry. For example, if you have granularity as hours and _expiry as 1 day it is possible that the data stays till 30 days from _ts

granularity	Covered Time Span
seconds	one hour
minutes	24 hours
hours	30 days

Request body example#

[  {    "_name": "Temperature Sensors Collection",    "_shortName": "tempsensor",    "_description": "Temperature Sensor IoT",    "_itemClass": "NamedTelemetryCollection",    "_namespaces": [      "Lnt_GglJp74V"    ],    "_userType": "iaf_telemetry_timeseries",    "_tsProperties": {      "_granularity": "minutes",      "_expiry": 86400    }  }]

Response#

Response codes#

Code	Description
`201`	Created
`400`	Bad Request

Response#

{  "_pageSize": 1,  "_list": [    {      "_uri": "/nameduseritems/62bef77bc21eca157f108e1f",      "_name": "Temperature Sensors Collection",      "_userType": "iaf_telemetry_timeseries",      "_tipId": "62bef77bc21eca157f108e20",      "_versions": [        {          "_userItemDbId": "62bef77bc21eca157f108e1f",          "_id": "62bef77bc21eca157f108e20",          "_isTip": true,          "_metadata": {            "_updatedById": "057ce6fd-a306-4bdc-8514-0a45c453f7ec",            "_createdAt": 1656682375086,            "_createdById": "057ce6fd-a306-4bdc-8514-0a45c453f7ec",            "_updatedAt": 1656682375086          },          "_version": 1        }      ],      "_irn": "itemsvc:nameduseritem:62bef77bc21eca157f108e1f",      "_tsProperties": {        "_expiry": 86400,        "_granularity": "minutes"      },      "_namespaces": [        "Lnt_GglJp74V"      ],      "_nextVersion": 2,      "_shortName": "tempsensor",      "_tipVersion": 1,      "_versionsCount": 1,      "_itemClass": "NamedTelemetryCollection",      "_userItemId": "tempsensor_LKdKJL7cfy",      "_id": "62bef77bc21eca157f108e1f",      "_description": "Temperature Sensor IoT",      "_metadata": {        "_updatedById": "057ce6fd-a306-4bdc-8514-0a45c453f7ec",        "_createdAt": 1656682374059,        "_createdById": "057ce6fd-a306-4bdc-8514-0a45c453f7ec",        "_updatedAt": 1656682374059      },      "_kind": "collection"    }  ],  "_offset": 0,  "_total": 1}

Get Named Telemetry Collections#

Optionally filtered by query

Endpoints#

GET /itemsvc/api/v1/nameduseritems

Request#

Query parameters#

Parameter	Type	Description	Required
`query`	Object	Pass a query object with query parameters and values based on the NamedTelemetryCollection class. You can also use query operators. To query all versions of NamedTelemetryCollection rather than just the latest versions, add the query property and value `_versions.all: true`. For query examples, see Query parameter examples.	Optional
`project`	Object	Field projections to exclude or include fields in the response, for example, `project={"_metadata":0}`.	Optional
`page`	Object	Pass a Page object that defines the response pagination, for example, `?page={"_offset": 0, "_pageSize" 100}`	Optional
`sort`	Object	Pass a sort object to define the response sort order by a given property, using `1` for ascending sort and `-1` for descending sort, for example, `?sort={"_name":1}`	Optional
`userItemVersionId`	Object	Lookup RelatedItems for a given NamedTelemetryCollection version, rather than the current version.	Optional
`nsfilter`	String	namespace context	Required

Examples:

# searches by name, the response would have tip version only:?query={"_name": "General Medical Sensor data"}
# searches by item class, has all the versions?query={"_itemClass": "NamedTelemetryCollection","_versions.all":true}
# searches against all the versions and returns all the versions matching?query={"$and": [{"_itemClass": "NamedTelemetryCollection"},{"_versions._userAttributes.key":"value"}],"_versions.all":true}
# searches against latest version?query={"$and": [{"_itemClass": "NamedTelemetryCollection"},{"_versions._userAttributes.key":"value":"value"}]}

Response#

Response codes#

Code	Description
`200`	Success
`400`	Bad Request

Response body example#

{  "_pageSize": 1,  "_list": [    {      "_uri": "/nameduseritems/62bef77bc21eca157f108e1f",      "_name": "Temperature Sensors Collection",      "_userType": "iaf_telemetry_timeseries",      "_tipId": "62bef77bc21eca157f108e20",      "_versions": [        {          "_userItemDbId": "62bef77bc21eca157f108e1f",          "_id": "62bef77bc21eca157f108e20",          "_isTip": true,          "_metadata": {            "_updatedById": "057ce6fd-a306-4bdc-8514-0a45c453f7ec",            "_createdAt": 1656682375086,            "_createdById": "057ce6fd-a306-4bdc-8514-0a45c453f7ec",            "_updatedAt": 1656682375086          },          "_version": 1        }      ],      "_irn": "itemsvc:nameduseritem:62bef77bc21eca157f108e1f",      "_tsProperties": {        "_expiry": 86400,        "_granularity": "minutes"      },      "_namespaces": [        "Lnt_GglJp74V"      ],      "_nextVersion": 2,      "_shortName": "tempsensor",      "_tipVersion": 1,      "_versionsCount": 1,      "_itemClass": "NamedTelemetryCollection",      "_userItemId": "tempsensor_LKdKJL7cfy",      "_id": "62bef77bc21eca157f108e1f",      "_description": "Temperature Sensor IoT",      "_metadata": {        "_updatedById": "057ce6fd-a306-4bdc-8514-0a45c453f7ec",        "_createdAt": 1656682374059,        "_createdById": "057ce6fd-a306-4bdc-8514-0a45c453f7ec",        "_updatedAt": 1656682374059      },      "_kind": "collection"    }  ],  "_offset": 0,  "_total": 1}

Get Named Telemetry Collections by Id#

Endpoints#

GET /itemsvc/api/v1/nameduseritems/{id}

Request#

Path parameters#

Parameter	Type	Description	Required
`id`	String	Pass the NamedTelemetryCollection `_id` or `_userItemId` value.	Required

Query parameters#

Parameter	Type	Description	Required
`project`	String	Field projections to exclude or include fields in the response, for example, `project={"_metadata":0}`.	Optional
`_versions.all`	String	Add `_versions.all` to your query to get all the NamedTelemetryCollection's versions.	Optional
`nsfilter`	String	namespace context	Required

Response#

Response codes#

Code	Description
`200`	Success
`400`	Bad Request

Response body example#

{  "_uri": "/nameduseritems/62bef77bc21eca157f108e1f",  "_name": "Temperature Sensors Collection",  "_userType": "iaf_telemetry_timeseries",  "_tipId": "62bef77bc21eca157f108e20",  "_versions": [    {      "_userItemDbId": "62bef77bc21eca157f108e1f",      "_id": "62bef77bc21eca157f108e20",      "_isTip": true,      "_metadata": {        "_updatedById": "057ce6fd-a306-4bdc-8514-0a45c453f7ec",        "_createdAt": 1656682375086,        "_createdById": "057ce6fd-a306-4bdc-8514-0a45c453f7ec",        "_updatedAt": 1656682375086      },      "_version": 1    }  ],  "_irn": "itemsvc:nameduseritem:62bef77bc21eca157f108e1f",  "_tsProperties": {    "_expiry": 86400,    "_granularity": "minutes"  },  "_namespaces": [    "Lnt_GglJp74V"  ],  "_nextVersion": 2,  "_shortName": "tempsensor",  "_tipVersion": 1,  "_versionsCount": 1,  "_itemClass": "NamedTelemetryCollection",  "_userItemId": "tempsensor_LKdKJL7cfy",  "_id": "62bef77bc21eca157f108e1f",  "_description": "Temperature Sensor IoT",  "_metadata": {    "_updatedById": "057ce6fd-a306-4bdc-8514-0a45c453f7ec",    "_createdAt": 1656682374059,    "_createdById": "057ce6fd-a306-4bdc-8514-0a45c453f7ec",    "_updatedAt": 1656682374059  },  "_kind": "collection"}

Delete Named Telemetry Collection by Id#

Same as in NamedUserCollection

Create Telemetry items in a Named Telemetry Collection#

Endpoints#

POST /itemsvc/api/v1/nameduseritems/{id}/relateditems

Request#

Path parameters#

Parameter	Type	Description	Required
`id`	String	Pass the NamedTelemetryCollection `_id` or `_userItemId` value.	Required

Query parameters#

Parameter	Type	Description	Required
`userItemVersionId`	String	Pass the userItemVersionId to target a specific NamedTelemetryCollection version.	Optional
`transactional`	String	Set to true to make the request transactional.	Optional
`nsfilter`	String	namespace context	Required

Body parameters#

Parameter	Type	Description	Required
`_sourceId`	String	Source id of the item that generates the readings. For example, a sensor id.	Required

Body example#

[  {    "floorname": "2nd Floor",    "roomname": "Lab",    "_sourceId": "e3e052f9-0156-11d5-9301-0000863f27ad-00000131"  },  {    "floorname": "2nd Floor",    "roomname": "Library",    "_sourceId": "a2e052a6-9126-21d5-7301-0000863f27ad-3450121"  }]

Response#

Response codes#

Code	Description
`201`	Created
`400`	Bad Request

Response#

{  "_pageSize": 2,  "_list": [    {      "roomname": "Lab",      "_uri": "/nameduseritems/62bee069c21eca157f108e17/relateditems/62befda2c21eca157f108e21",      "_sourceId": "e3e052f9-0156-11d5-9301-0000863f27ad-00000131",      "_id": "62befda2c21eca157f108e21",      "_metadata": {        "_updatedById": "057ce6fd-a306-4bdc-8514-0a45c453f7ec",        "_createdAt": 1656683938707,        "_createdById": "057ce6fd-a306-4bdc-8514-0a45c453f7ec",        "_updatedAt": 1656683938707      },      "floorname": "2nd Floor"    },    {      "roomname": "Library",      "_uri": "/nameduseritems/62bee069c21eca157f108e17/relateditems/62befda2c21eca157f108e22",      "_sourceId": "a2e052a6-9126-21d5-7301-0000863f27ad-3450121",      "_id": "62befda2c21eca157f108e22",      "_metadata": {        "_updatedById": "057ce6fd-a306-4bdc-8514-0a45c453f7ec",        "_createdAt": 1656683938709,        "_createdById": "057ce6fd-a306-4bdc-8514-0a45c453f7ec",        "_updatedAt": 1656683938709      },      "floorname": "2nd Floor"    }  ],  "_offset": 0,  "_total": 2}

Create Telemetry Items in a Named Telemetry Collection in Bulk#

Endpoints#

POST /itemsvc/api/v1/nameduseritems/{id}/relateditems/bulk

Request#

Path parameters#

Parameter	Type	Description	Required
`id`	String	Pass the NamedTelemetryCollection `_id` or `_userItemId` value.	Required

Query parameters#

Parameter	Type	Description	Required
`userItemVersionId`	String	Pass the NamedUserCollection `userItemVersionId` if you want to add to a specific version.	Optional
`transactional`	String	Set to true to make the request transactional.	Optional
`nsfilter`	String	namespace context	Required

Body parameters#

Max request body size: 10MB

Parameter	Type	Description	Required
`_sourceId`	String	The source id of the item that generates readings, for example, the sensor's id.	Optional

Body data example#

[  {    "floorname": "2nd Floor",    "roomname": "Lab",    "_sourceId": "e3e052f9-0156-11d5-9301-0000863f27ad-00000131"  }]

Response#

Response codes#

Code	Description
`201`	Created
`202`	Accepted
`400`	Bad Request

Response header#

Contains a URL to poll the status of the request.

Get Telemetry Items in a Named Telemetry Collection#

Follow the NamedUserCollection documentation for Get Related Items in a Named User Collection

Update a Telemetry Item by ID#

Follow the NamedUserCollection documentation for Update a Related Item by ID

Update Telemetry Items#

Follow the NamedUserCollection documentation for Update Related Items

Update Telemetry Items Bulk#

Follow the NamedUserCollection documentation for Update Related Items Bulk

Delete a Telemetry Item in a Named Telemetry Collection by Id#

Follow the NamedUserCollection documentation for Delete a Related Item by Id

Add Relationships For Telemetry Items in Named Telemetry Collection#

Follow the NamedUserCollection documentation for Add relationships Across Collections

Bulk Add Relationships For Telemetry Items in Named Telemetry Collection#

Follow the NamedUserCollection documentation for Bulk Update Relationships Between Collections

Get Relationships in a Named Telemetry Collection#

Follow the NamedUserCollection documentation for Get Relationships in a Named User Collection

Get Inverse relationships in a NamedUserCollection#

Follow the NamedUserCollection documentation for Get Inverse relationships in a NamedUserCollection

Delete Relationship for a Telemetry Item#

Follow the NamedUserCollection documentation for Delete Relationship for a RelatedItem

Get all Indexes for a Named Telemetry Collection#

Follow the NamedUserCollection documentation for Get all Indexes for a Named User Collection

Create Indexes for a Named Telemetry Collection#

Follow the NamedUserCollection documentation for Create Indexes for a Named User Collection

Create Readings for a Telemetry Item#

Endpoints#

POST /itemsvc/api/v1/nameduseritems/:id/relateditems/readings

Request#

Query parameters#

Parameter	Type	Description	Required
`userItemVersionId`	String	Pass the NamedUserCollection `userItemVersionId` if you want to add to a specific version.	Optional
`nsfilter`	String	namespace context	Required

Path parameters#

Parameter	Type	Description	Required
`_ts`	String	A timestamp in ISO timestamp format YYYY-MM-DDTHH:MM:SSZ.	Required
`_tsMetadata._telItemId`	String	TelemetryItem id	Required
`_tsMetadata._sourceId`	String	The sensor source id for the TelemetryItem referenced in `_tsMetadata._telItemId`.	Required

Example:

[  {    "_ts":"2022-07-02T05:15:30+05:30",    "_tsMetadata": {      "_telItemId": "62befda2c21eca157f108e22",      "_sourceId": "a2e052a6-9126-21d5-7301-0000863f27ad-3450121"    }  }]

Response#

Response codes#

Code	Description
`204`	Success, No content
`400`	Bad Request

Response data#

None

Get Readings in a Telemetry collection#

Endpoints#

GET /itemsvc/api/v1/nameduseritems/:id/relateditems/readings

Parameters#

Request#

Path parameters#

Parameter	Type	Description	Required
`id`	String	Pass the NamedTelemetryCollection `_id` or `_userItemId` value.	Required

Query parameters#

Parameter	Type	Description	Required
`query`	Object	Pass a query object with query parameters and values based on the NamedTelemetryCollection class. You can also use query operators. To query all versions of NamedTelemetryCollections rather than just the latest versions, add the query property and value `_versions.all: true`. For query examples, see Query parameter examples.	Optional
`project`	Object	Field projections to exclude or include fields in the response, for example, `project={"_metadata":0}`.	Optional
`page`	Object	Pass a Page object that defines the response pagination, for example, `?page={"_offset": 0, "_pageSize" 100}`	Optional
`sort`	Object	Pass a sort object to define the response sort order by a given property, using `1` for ascending sort and `-1` for descending sort, for example, `?sort={"_name":1}`	Optional
`userItemVersionId`	Object	Lookup RelatedItems for a given NamedUserCollection version, rather than the current version.	Optional
`nsfilter`	String	namespace context	Required

Query parameter examples#

# searches by _telItemId:?query={"_tsMetadata._telItemId":"62bfad5f292eda1aadbe2d74"}
# searches by _sourceId?query={"_tsMetadata._sourceId":"a2e052a6-9126-21d5-7301-0000863f27ad-3450121"}
# searches by _ts, timestamp (ISO timestamp format YYYY-MM-DDTHH:MM:SSZ, Z represents the time zone, with "Z" indicating UTC, or it can be replaced with the time zone offset from UTC)Ex: `2022-07-02T20:15:30+05:30`, `2022-07-03T15:15:30Z`?query={"_ts":{"$gt": "2022-07-03T00:10:30Z"}}?query={"_ts":{"$gt": "2022-07-02T09:10:30%2B05:30"}}

Aggregate Query on Readings#

Endpoints#

POST /itemsvc/api/v1/nameduseritems/:id/relateditems/readings/aggregate

Query#

nsfilter - namespace context (Required)

Body#

Array of aggregation stages. For a list of supported stages, refer to Supported aggregation pipeline stages.

Body example#

The following aggregation finds the average temperature in given time boundaries:

[  {    "$match": {      "temp": {        "$exists": true      }    }  },  {    "$project": {      "temp": 1,      "_tsMetadata": 1,      "tsAsString": {        "$dateToString": {          "date": "$_ts",          "format": "%Y-%m-%dT%H:%M:%S:%L%Z"        }      }    }  },  {    "$bucket": {      "groupBy": "$tsAsString",      "boundaries": [        "2023-05-09T00:00:00Z",        "2023-05-09T01:00:00Z",        "2023-05-10T00:00:00Z",        "2023-05-11T00:00:00Z",        "2023-05-12T00:00:00Z"      ],      "default": "Other",      "output": {        "count": {          "$sum": 1        },        "avgValue": {          "$avg": "$temp"        }      }    }  }]

Response#

Response codes#

Code	Description
`200`	Success
`400`	Bad Request
`422`	Unprocessable entity if query execution exceeds 30 secs
`429`	Too many requests

Response#

{  "_list": [    {      "avgValue": 520.5,      "count": 24,      "_id": "2023-05-10T00:00:00Z"    },    {      "avgValue": 374.7,      "count": 10,      "_id": "2023-05-11T00:00:00Z"    },    {      "avgValue": 611.6470588235294,      "count": 17,      "_id": "Other"    }  ]}