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	Integer	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": "seconds"
      },
      "_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"
    }
  ]
}