Skip to main content
Version: v4.6

Telemetry Configs

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/telemetryconfigs?nsfilter=proj_DrZrSNrW

Create Telemetry Config​

Creates a telemetry configuration for IoT integration.

Endpoints​

POST /itemsvc/api/v1/telemetryconfigs

Request​

Query parameters​

ParameterTypeDescriptionRequired
nsfilterStringnamespace contextRequired

Request body parameters​

PropertyTypeDescriptionRequired
_nameStringName your telemetry configuration in long form with a maximum of 100 characters.Required
_userTypeStringEnter a new or shared custom type with a maximum of 100 characters.Required
_configDataObjectPass an object with your config data.Required
_configData._bindingsArray of ObjectPass an array that contains your bindings objects.Required
_configData._bindings.collectionDescObjectPass an object with a "_userItemId" property.Required
_configData._bindings.collectionDesc._userItemIdStringThe user item id of the named telemetry collection.Required
_configData._bindings.queryObjectPass an object with a "query" property.Required
_configData._bindings.query.deviceTypeStringRequired
_configData._normalizationScriptObjectPass an object with a "_userType" property.Required
_configData._normalizationScript._userTypeStringEnter your normalization script's _userType value.Required
_namespacesArray of StringEnter the namespace that you want to own the telemetry configuration.Required
_shortNameStringGive your telemetry configuration an abbreviated name with a maximum of 22 characters.Required
_descriptionStringEnter a description for the telemetry configurationRequired
Request body example​
{
  "_name": "Telemetry Config - 1",
  "_userType": "telemetry_config",
  "_configData": {
    "_bindings": [
      {
        "collectionDesc": {
          "_userItemId": "tempsensor_gBDjAv6dl4"
        },
        "query": {
            "deviceType": "temp-10"
        }
      }
    ],
    "_normalizationScript":{
      "_userType":"telemetry_parser_script"
    }
  },
  "_namespaces": [
    "automation_3E4tpXPu"
  ],
  "_shortName": "telconfig",
  "_description": "Telemetry Config for project A"
}

Response​

Response codes​

CodeDescription
202Accepted
400Bad Request

Response header​

HeaderDescription
LocationContains the URL for the Telemetry Config Status API.
Example​
https://xxxxxx.com/itemsvc/api/v1/telemetry_async_tasks/7d6bdcbf-67ab-44f5-8634-dd6dfa48f6c4

Get All Telemetry Configs​

Gets all telemetry configurations.

Endpoints​

GET /itemsvc/api/v1/telemetryconfigs

Request​

Query parameters​

ParameterTypeDescriptionRequired
nsfilterStringFilter the telemetry configs by namespace.Optional

Response​

Response codes​

CodeDescription
200Success

Response body example​

{
  "_pageSize": 1,
  "_list": [
    {
      "_uri": "/telemetryconfigs/64c7c8c6b77e3b2ff378e449",
      "_namespaces": [
        "automation_3E4tpXPu"
      ],
      "_name": "Telemetry Config - 1",
      "_shortName": "telconfig",
      "_userType": "telemetry_config",
      "_irn": "itemsvc:telemetryconfig:64c7c8c6b77e3b2ff378e449",
      "_id": "64c7c8c6b77e3b2ff378e449",
      "_description": "Telemetry Config for project A",
      "_metadata": {
        "_updatedById": "c9b79905-2106-4d21-8ec1-4a58b7143e9f",
        "_createdAt": 1690814662033,
        "_createdById": "c9b79905-2106-4d21-8ec1-4a58b7143e9f",
        "_updatedAt": 1690814662033
      },
      "_configData": {
        "_normalizationScript": {
          "_userType": "telemetry_parser_script"
        },
        "_bindings": [
          {
            "collectionDesc": {
              "_userItemId": "tempsensor_gBDjAv6dl4"
            }
          }
        ],
        "_sources": [
          {
            "_connector": "jms",
            "_channel": "activemq"
          }
        ]
      }
    }
  ],
  "_offset": 0,
  "_total": 1
}

Get Telemetry Configs By Id​

Endpoints​

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

Request​

Path parameters​

ParameterTypeDescriptionRequired
idStringThe telemetry config's idRequired

Query parameters​

ParameterTypeDescriptionRequired
nsfilterStringFilter the telemetry configs by namespace.Required

Response​

Response codes​

CodeDescription
200Success
404Resource Not Found

Response body example​

{
  "_updateLogs": [
    {
      "_updatedBy": "c9b79905-2106-4d21-8ec1-4a58b7143e9f",
      "_updatedAt": 1690814662033
    }
  ],
  "_uri": "/telemetryconfigs/64c7c8c6b77e3b2ff378e449",
  "_namespaces": [
    "automation_3E4tpXPu"
  ],
  "_name": "Telemetry Config - 1",
  "_shortName": "telconfig",
  "_userType": "telemetry_config",
  "_irn": "itemsvc:telemetryconfig:64c7c8c6b77e3b2ff378e449",
  "_id": "64c7c8c6b77e3b2ff378e449",
  "_description": "Telemetry Config for project A",
  "_metadata": {
    "_updatedById": "c9b79905-2106-4d21-8ec1-4a58b7143e9f",
    "_createdAt": 1690814662033,
    "_createdById": "c9b79905-2106-4d21-8ec1-4a58b7143e9f",
    "_updatedAt": 1690814662033
  },
  "_configData": {
    "_normalizationScript": {
      "_userType": "telemetry_parser_script"
    },
    "_bindings": [
      {
        "collectionDesc": {
          "_userItemId": "tempsensor_gBDjAv6dl4"
        }
      }
    ],
    "_sources": [
      {
        "_connector": "jms",
        "_channel": "activemq"
      }
    ]
  }
}

Delete Telemetry Configs By Id​

Endpoints​

DELETE /itemsvc/api/v1/telemetryconfigs/{id}

Request​

Path parameters​

ParameterTypeDescriptionRequired
idStringThe telemetry config's id you want to deleteRequired

Query parameters​

ParameterTypeDescriptionRequired
nsfilterStringFilter by namespaceOptional

Response​

Response codes​

CodeDescription
202Accepted
404Resource Not Found

Response header​

HeaderDescription
LocationContains the URL for the Telemetry Config Status API.
Example​
https://xxxxxx.com/itemsvc/api/v1/telemetry_async_tasks/7d6bdcbf-67ab-44f5-8634-dd6dfa48f6c4

Update Telemetry Configs By Id​

Endpoints​

PUT /itemsvc/api/v1/telemetryconfigs/{id}

Request​

Path parameters​

ParameterTypeDescriptionRequired
idStringThe id of the telemetry config you want to updateRequired

Query parameters​

ParameterTypeDescriptionRequired
nsfilterStringFilter the telemetry configs by namespaceRequired

Body parameters​

ParameterTypeDescriptionRequired
_nameStringName your telemetry configuration in long form with a maximum of 100 characters.Required
_shortNameStringGive your telemetry configuration an abbreviated name with a maximum of 22 characters.Required
_descriptionEnter a description for the telemetry configurationDescription of the Config
_namespacesArray of StringThe namespaces you want to add the created configuration to.
_userTypeStringEnter a new or shared custom type with a maximum of 100 characters.
_configDataObjectPass your telemetry configuration data as an object./Config Data for the Telemetry Config
Request body example​
{
  "_name": "Telemetry Config - 1",
  "_userType": "telemetry_config",
  "_configData": {
    "_sources": [
      {
        "_connector": "jms",
        "_channel": "activemq"
      }
    ],
    "_bindings": [
      {
        "collectionDesc": {
          "_userItemId": "tempsensor_gBDjAv6dl4"
        },
        "query": {
            "deviceType": "temp-10"
        }
      }
    ],
    "_normalizationScript":{
      "_userType":"telemetry_parser_script"
    }
  },
  "_namespaces": [
    "automation_3E4tpXPu"
  ],
  "_shortName": "telconfig",
  "_description": "Telemetry Config for project A"
}

Response​

Response codes​

CodeDescription
202Accepted
404Resource Not Found

Response header​

HeaderDescription
LocationContains the URL for the Telemetry Config Status API.
Example​
https://xxxxxx.com/itemsvc/api/v1/telemetry_async_tasks/7d6bdcbf-67ab-44f5-8634-dd6dfa48f6c4