IoTHub RESTful version v3
http://elco.iothub/{version}
Public API of the IoTHub by ELCO Industry Automation
- version: required(v3)
Request types
There are several HTTP request types. The REST interface of the IoTHub uses 5 of them.
- GET - Retrieve some data from the IoTHub
- POST - Add resources or trigger functions
- PUT - Assign/Revoke resources
- PATCH - Update resources
- DELETE - Delete resources
Each request needs to be authorised with an access token in the header.
Usage: Authorization => "Bearer access_token"
Replace access_token with the token received after login or refresh endpoints (user authentication)
GET requests with optional query parameters work as follows:
- /iam/users?names=admin,janedoe (filter user list for names admin and janedoe)
Response types
The following response status codes can appear on every endpoint and represent errors in the request or internal failures:
- 400: Bad request:
Something went wrong with the request.
There might be properties missing or the json is malformed. - 401: Unauthorized:
The request cannot be authorized.
Confirm that your access token is valid and present in the header. - 403: Forbidden:
User is not allowed to access the requested resource. - 404: Not found:
The requested resource can not be found.
The neccessary ID or name might be wrong or malformed. - 405: Method not allowed:
The used HTTP request method (POST, PUT etc.) is not correct. - 409: Conflict:
The requested resource was previously assigned or already exists. - 500: Internal server error:
There has been an internal error. Please contact the development team. - 503: Service unavailable:
The service is temporarily not available. Please try again later.
All other responses are explained on the individual endpoint pages.
Version information
Delivers the version of the IoTHub
Gets the version of the IoTHub
get /version
Gets the version of the IoTHub
HTTP status code 200
Body
Media type: application/json
Type: object
Properties- version: required(string)
Official version of the IoTHub
- commit: required(string)
Commit hash of the build of the IoTHub
- built: required(string)
Date and time of the build of the IoTHub
Example:
{
"version": "3.0.0",
"commit": "4787dae6",
"built": "28.05.2021 09:46:35"
}
License information
Delivers information about the license of the IoTHub
Gets the license state of the IoTHub
get /license
Gets the license state of the IoTHub
Delivers the details of the license
get /license/details
Delivers the details of the license
HTTP status code 200
Body
Media type: application/json
Type: object
Properties- Id: required(string)
Id of the license
Example:
864153761998997503 - Version: required(string)
Version of the license key
Example:
7.100 - Hw_version: (string)
Version of the license dongle
- Key_model: required(string)
A model description of the key
Example:
Certificate - product: required(object)
Product information about the licensed product
- id: required(string)
Article id of the product
- name: required(string)
Name of the product
- feature: required(array of licenseLib.FeatureInfo)
Items: FeatureInfo
- id: required(number)
Id of the feature
- name: required(string)
Name of the feature
- usable: required(boolean)
Feature is allowed within the license
- active: required(boolean)
Feature is activated in this license
- id: required(number)
Example:
{ "id": "666", "name": "IoT Hub", "feature": [{ "id": 101, "name": "Hub Core", "usable": true, "active": true }] } - id: required(string)
- counter: required(object)
Information about license limits. If not set for a category, the license is unlimited. Categories can be properties, agent types, users and things. An unlimited category does not existing in the response.
- current: required(number)
Number of used (users/agents/properties/things) slots
- maximum: required(number)
Maximum number of allowed (users/agents/properties/things) slots
- error: (string)
Example:
{ "counter": { "agent_types": { "current": 0, "maximum": 52 } } } - current: required(number)
Example:
{
"license": {
"id": "0815",
"version": "4.69",
"hw_version": "8.10",
"key_model": "Maxi",
"product": [{
"id": "666",
"name": "IoT Hub",
"feature": [{
"id": 101,
"name": "Hub Core",
"usable": true,
"active": true
}, {
"id": 5,
"name": "Workflow Module",
"usable": true,
"active": true
}, {
"id": 103,
"name": "History Module",
"usable": true,
"active": true
}, {
"id": 104,
"name": "Gateway Module",
"usable": true,
"active": true
}]
}, {
"id": "669",
"name": "App Designer",
"feature": [{
"id": 501,
"name": "App Designer Module",
"usable": true,
"active": true
}]
}],
"counter": {
"agent_types": {
"current": 0,
"maximum": 52
},
"properties": {
"current": 0,
"maximum": 65
}
}
}
}
User authentication and authorization
Login, Logout, password changes etc.
login to IoTHub for access token
post /auth/login
login to IoTHub for access token
Body
Media type: application/json
Type: object
Properties- username: required(string)
the users name
- password: required(string)
the users password
Example:
{
"username": "johndoe",
"password": "p@ssw0rd"
}
HTTP status code 200
OK
Body
Media type: application/json
Type: object
Properties- scopes: required(array of userLib.ScopeName)
list of accessible scopes
- access_token: required(string)
access token
- token_type: required(string - default: bearer)
type of usage for the access token
- expires_in: required(integer)
time until access token expires (in seconds)
- refresh_token: required(string)
refresh token for generating new access tokens
- username: required(string)
the users name
Example:
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MSwidXNlcm5hbWUiOiJhZG1pbiIsInJvbGVzIjpbImFkbWluIl0sImF1ZCI6ImFjY2VzcyIsImV4cCI6MTU3NDg2MjA5MiwiaWF0IjoxNTc0ODYxMTkyfQ.HYnX-xoe95pcmCAYS6QQmKGmERmcLALdofo_peYSruk",
"token_type": "bearer",
"expires_in": 900,
"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MSwidXNlcm5hbWUiOiJhZG1pbiIsInJvbGVzIjpbImFkbWluIl0sImF1ZCI6InVzZXIiLCJleHAiOjE1Nzc0NTMxOTIsImlhdCI6MTU3NDg2MTE5Mn0.lDB5HAzj21EGJ3hGnZSZLe1_jcK2IJdoTYYkGjsNQpk",
"username": "johndoe",
"scopes": ["workflows","things"]
}
logout user and invalidate refresh token
post /auth/logout
logout user and invalidate refresh token
Body
Media type: application/json
Type: object
Properties- refresh_token: required(string)
refresh token for generating new access tokens
Example:
{
"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MSwidXNlcm5hbWUiOiJhZG1pbiIsInJvbGVzIjpbImFkbWluIl0sImF1ZCI6InVzZXIiLCJleHAiOjE1Nzc0NTMxOTIsImlhdCI6MTU3NDg2MTE5Mn0.lDB5HAzj21EGJ3hGnZSZLe1_jcK2IJdoTYYkGjsNQpk"
}
HTTP status code 200
OK
lougout user and invalidate token
post /auth/refresh
lougout user and invalidate token
Body
Media type: application/json
Type: object
Properties- refresh_token: required(string)
refresh token for generating new access tokens
Example:
{
"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MSwidXNlcm5hbWUiOiJhZG1pbiIsInJvbGVzIjpbImFkbWluIl0sImF1ZCI6InVzZXIiLCJleHAiOjE1Nzc0NTMxOTIsImlhdCI6MTU3NDg2MTE5Mn0.lDB5HAzj21EGJ3hGnZSZLe1_jcK2IJdoTYYkGjsNQpk"
}
HTTP status code 200
OK
Body
Media type: application/json
Type: object
Properties- access_token: required(string)
access token
- token_type: required(string - default: bearer)
type of usage for the access token
- expires_in: required(integer)
time until access token expires (in seconds)
- scopes: required(array of userLib.ScopeName)
list of accessible scopes
Example:
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MSwidXNlcm5hbWUiOiJhZG1pbiIsInJvbGVzIjpbImFkbWluIl0sImF1ZCI6ImFjY2VzcyIsImV4cCI6MTU3NDg2MjA5MiwiaWF0IjoxNTc0ODYxMTkyfQ.HYnX-xoe95pcmCAYS6QQmKGmERmcLALdofo_peYSruk",
"token_type": "bearer",
"expires_in": 900,
"scopes": ["workflows","things"]
}
Updates the password of an user at the IoTHub
put /auth/password
Updates the password of an user at the IoTHub
Body
Media type: application/json
Type: object
Properties- username: required(string)
the users name
- password: required(string)
the users password
- confirmation: required(string)
the users password
Example:
{
"username": "johndoe",
"password": "p@ssw0rd",
"confirmation": "p@ssw0rd"
}
HTTP status code 200
OK
Get e-mail for forgotten password
post /auth/password-forgotten
Reset password and get a new one
User management
Add, delete, change and deliver user
Gets (all) users added to the IoTHub
Adds a user to the IoTHub
get /iam/users
Gets (all) users added to the IoTHub
Query Parameters
- names: (string)
A comma separated list of user names to search for
HTTP status code 200
OK
Body
Media type: application/json
Type: array of userLib.UserReturnObject
Items: UserReturnObject
- username: required(string)
the users name
- userinfo: required(object)
first/last name and e-mail address
- forename: (string)
users first name(s)
- lastname: (string)
users last name(s)
- email: required(string)
the users e-mail
- forename: (string)
- roles: required(array of userLib.RoleName)
array of strings containing the users roles
- groups: required(array of userLib.GroupName)
array of strings containing the users groups
- all_roles: required(array of userLib.RoleName)
array of strings containing the names of the all roles assigned to the user (from roles and groups)
- created_at: required(integer)
timestamp of creation
Example:
[
{
"username": "johndoe",
"userinfo": {
"forename": "John",
"lastname": "Doe",
"email" : "jon.doe@elco-automation.de"
},
"roles" : [
"admin"
],
"groups" : [
"admin-thing",
"admin-user"
],
"all_roles" : [
"admin-role",
"thing-role",
"user-role"
],
"created_at": 1568027832
},
{
"username": "janedoe",
"userinfo": {
"email" : "jane.doe@elco-automation.de"
},
"roles" : [
"admin"
],
"groups" : [
"admin-thing",
"admin-group"
],
"all_roles" : [
"admin-role",
"thing-role",
"group-role"
],
"created_at": 1568027832
}
]
post /iam/users
Adds a user to the IoTHub
Body
Media type: application/json
Type: object
Properties- username: required(string)
the users name
- userinfo: required(object)
first/last name and e-mail address
- forename: (string)
users first name(s)
- lastname: (string)
users last name(s)
- email: required(string)
the users e-mail
- forename: (string)
- password: required(string)
the users password
- roles: (array of userLib.RoleName)
array of strings containing the names of the roles directly assigned to the user
- groups: (array of userLib.GroupName)
array of strings containing the names of the groups directly assigned to the user
Example:
{
"username": "johndoe",
"userinfo": {
"forename": "John",
"lastname": "Doe",
"email" : "jon.doe@elco-automation.de"
},
"password": "p@ssw0rd",
"roles" : [
"super-role"
],
"groups" : [
"super-group"
]
}
HTTP status code 200
OK
Body
Media type: application/json
Type: object
Properties- username: required(string)
the users name
- userinfo: required(object)
first/last name and e-mail address
- forename: (string)
users first name(s)
- lastname: (string)
users last name(s)
- email: required(string)
the users e-mail
- forename: (string)
- roles: required(array of userLib.RoleName)
array of strings containing the users roles
- groups: required(array of userLib.GroupName)
array of strings containing the users groups
- all_roles: required(array of userLib.RoleName)
array of strings containing the names of the all roles assigned to the user (from roles and groups)
- created_at: required(integer)
timestamp of creation
Example:
{
"username": "johndoe",
"userinfo": {
"forename": "John",
"lastname": "Doe",
"email": "jon.doe@elco-automation.de"
},
"roles": [
"admin-things"
],
"groups": [
"assembly-lines",
"production-lines"
],
"all_roles" : [
"super-role",
"production-role",
"assembly-role"
],
"created_at": 1583227647357
}
Gets the user
Updates the user information at the IoTHub
Deletes the user from the IoTHub
get /iam/users/{username}
Gets the user
URI Parameters
- username: required(string)
the users name
HTTP status code 200
OK
Body
Media type: application/json
Type: object
Properties- username: required(string)
the users name
- userinfo: required(object)
first/last name and e-mail address
- forename: (string)
users first name(s)
- lastname: (string)
users last name(s)
- email: required(string)
the users e-mail
- forename: (string)
- roles: required(array of userLib.RoleName)
array of strings containing the users roles
- groups: required(array of userLib.GroupName)
array of strings containing the users groups
- all_roles: required(array of userLib.RoleName)
array of strings containing the names of the all roles assigned to the user (from roles and groups)
- created_at: required(integer)
timestamp of creation
Example:
{
"username": "johndoe",
"userinfo": {
"forename": "John",
"lastname": "Doe",
"email": "jon.doe@elco-automation.de"
},
"roles": [
"admin-things"
],
"groups": [
"assembly-lines",
"production-lines"
],
"all_roles" : [
"super-role",
"production-role",
"assembly-role"
],
"created_at": 1583227647357
}
put /iam/users/{username}
Updates the user information at the IoTHub
URI Parameters
- username: required(string)
the users name
Body
Media type: application/json
Type: object
Properties- userinfo: required(object)
first/last name and e-mail address
- forename: (string)
users first name(s)
- lastname: (string)
users last name(s)
- email: required(string)
the users e-mail
- forename: (string)
Example:
{
"userinfo": {
"forename": "john",
"lastname": "doe",
"email": "john.doe@elco-automation.de"
}
}HTTP status code 200
OK
Body
Media type: application/json
Type: object
Properties- username: required(string)
the users name
- userinfo: required(object)
first/last name and e-mail address
- forename: (string)
users first name(s)
- lastname: (string)
users last name(s)
- email: required(string)
the users e-mail
- forename: (string)
- roles: required(array of userLib.RoleName)
array of strings containing the users roles
- groups: required(array of userLib.GroupName)
array of strings containing the users groups
- all_roles: required(array of userLib.RoleName)
array of strings containing the names of the all roles assigned to the user (from roles and groups)
- created_at: required(integer)
timestamp of creation
Example:
{
"username": "johndoe",
"userinfo": {
"forename": "John",
"lastname": "Doe",
"email": "jon.doe@elco-automation.de"
},
"roles": [
"admin-things"
],
"groups": [
"assembly-lines",
"production-lines"
],
"all_roles" : [
"super-role",
"production-role",
"assembly-role"
],
"created_at": 1583227647357
}
Gets the app tokens of the user
Creates an app token by the identifier of the app token
get /iam/users/{username}/app-token
Gets the app tokens of the user
URI Parameters
- username: required(string)
the users name
HTTP status code 200
OK
Body
Media type: application/json
Type: array of object
Items: AppTokenResponse
- app_identifier: required(string - pattern: ^[a-zA-Z][\w-]{3,32}$)
name for an app token
- app_token: required(string)
the app token
- created_at: required(integer)
timestamp of creation
Example:
[
{
"app_identifier": "testdingens",
"app_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MSwiY2xhaW0iOiJ0ZXN0ZGluZ2VucyIsImF1ZCI6ImFwcCIsImlhdCI6MTU3NDk0MjYyOX0.QFBMFstd7xg1bBI_QDGzF0zjPNkhRzZOrwnsstrWD1U",
"created_at": 1574942629
},
{
"app_identifier": "testprodapp",
"app_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MSwiY2xhaW0iOiJ0ZXN0cHJvZGFwcCIsImF1ZCI6ImFwcCIsImlhdCI6MTU3NDk0MzI0NX0.XFZGGtQKVbFZM03X0nJtjzJ9hjhHODXmplpGqFNMQ2E",
"created_at": 1574943245
}
]post /iam/users/{username}/app-token
Creates an app token by the identifier of the app token
URI Parameters
- username: required(string)
the users name
Body
Media type: application/json
Type: any
HTTP status code 201
Created
Body
Media type: application/json
Type: object
Properties- app_identifier: required(string - pattern: ^[a-zA-Z][\w-]{3,32}$)
name for an app token
- app_token: required(string)
the app token
- created_at: required(integer)
timestamp of creation
Example:
{
"app_identifier": "testprodapp",
"app_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MSwiY2xhaW0iOiJ0ZXN0cHJvZGFwcCIsImF1ZCI6ImFwcCIsImlhdCI6MTU3NDk0MzI0NX0.XFZGGtQKVbFZM03X0nJtjzJ9hjhHODXmplpGqFNMQ2E",
"created_at": 1574943245
}
HTTP status code 403
Forbidden, app identifier name already exists
Gets the app tokens of the user with the given identifier
Deletes an app token with the given identifier
get /iam/users/{username}/app-token/{identifier}
Gets the app tokens of the user with the given identifier
URI Parameters
- username: required(string)
the users name
- identifier: required(string - pattern: ^[a-zA-Z][\w-]{3,32}$)
name for an app token
HTTP status code 200
OK
Body
Media type: application/json
Type: object
Properties- app_identifier: required(string - pattern: ^[a-zA-Z][\w-]{3,32}$)
name for an app token
- app_token: required(string)
the app token
- created_at: required(integer)
timestamp of creation
Example:
{
"app_identifier": "testprodapp",
"app_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MSwiY2xhaW0iOiJ0ZXN0cHJvZGFwcCIsImF1ZCI6ImFwcCIsImlhdCI6MTU3NDk0MzI0NX0.XFZGGtQKVbFZM03X0nJtjzJ9hjhHODXmplpGqFNMQ2E",
"created_at": 1574943245
}
Gets the groups linked to the user
Adds groups to the user
put /iam/users/{username}/groups
Removes groups from the user
put /iam/users/{username}/groups/remove
Gets the roles linked to the user
Adds roles to the user
put /iam/users/{username}/roles
Removes roles from the user
put /iam/users/{username}/roles/remove
Group management
Add, delete, change and deliver groups and grants roles and users to it
Gets all groups of the IoTHub
Adds a group to the IoTHub
get /iam/groups
Gets all groups of the IoTHub
Query Parameters
- groupname: (string)
A comma separated list of group names to search for
HTTP status code 200
OK
Body
Media type: application/json
Type: array of object
Items: GroupResponse
- name: required(string)
the name of the group
- description: required(string)
description of the group
- created_at: required(integer)
timestamp of creation
- roles: required(array of userLib.RoleName)
array of strings containing the names of connected roles
- users: required(array of userLib.UserName)
array of strings containing the user names of connected users
Example:
[
{
"name" : "journalists",
"description": "Reporters of the Daily Planet",
"created_at" : 156802783,
"roles" : ["thing_writer", "thing_reader", "thing-creator"],
"users" : ["superman", "supermanfan", "littlejimmy"]
},
{
"name" : "superheroes",
"description": "Super heroes of the world",
"created_at" : 156804629,
"roles" : ["workflow_all", "thing_all"],
"users" : ["superman", "supergirl", "dreamer", "flash"]
}
]post /iam/groups
Adds a group to the IoTHub
Body
Media type: application/json
Type: object
Properties- name: required(string)
name of the role or group
- description: required(string)
description of the role or group
Example:
{
"name": "admin-thing",
"description": "some description"
}
HTTP status code 200
OK
Body
Media type: application/json
Type: object
Properties- name: required(string)
the name of the group
- description: required(string)
description of the group
- created_at: required(integer)
timestamp of creation
- roles: required(array of userLib.RoleName)
array of strings containing the names of connected roles
- users: required(array of userLib.UserName)
array of strings containing the user names of connected users
Example:
{
"name": "admin-thing",
"description": "some description",
"created_at": 1574946116,
"roles": ["admin"],
"users": ["janedoe","johndoe"]
}
Gets the group
Updates the role name and/or description at the IoTHub
Deletes the group from the IoTHub
get /iam/groups/{groupname}
Gets the group
URI Parameters
- groupname: required(string)
Name of the group
HTTP status code 200
OK
Body
Media type: application/json
Type: object
Properties- name: required(string)
the name of the group
- description: required(string)
description of the group
- created_at: required(integer)
timestamp of creation
- roles: required(array of userLib.RoleName)
array of strings containing the names of connected roles
- users: required(array of userLib.UserName)
array of strings containing the user names of connected users
Example:
{
"name": "admin-thing",
"description": "some description",
"created_at": 1574946116,
"roles": ["admin"],
"users": ["janedoe","johndoe"]
}
patch /iam/groups/{groupname}
Updates the role name and/or description at the IoTHub
URI Parameters
- groupname: required(string)
Name of the group
Body
Media type: application/json
Type: object
Properties- name: required(string)
name of the role or group
- description: required(string)
description of the role or group
Example:
{
"name": "admin-thing",
"description": "some description"
}
HTTP status code 200
OK
Body
Media type: application/json
Type: object
Properties- name: required(string)
the name of the group
- description: required(string)
description of the group
- created_at: required(integer)
timestamp of creation
- roles: required(array of userLib.RoleName)
array of strings containing the names of connected roles
- users: required(array of userLib.UserName)
array of strings containing the user names of connected users
Example:
{
"name": "admin-thing",
"description": "some description",
"created_at": 1574946116,
"roles": ["admin"],
"users": ["janedoe","johndoe"]
}
Gets the members of the group
Adds users to the group
Removes the users from the group
Gets the roles granted to the group
Adds roles to the group
Removes the roles from the group
Role management
Add, delete, change, manage scopes, and deliver roles
Get all roles of the IoTHub
Adds a role to the IoTHub
get /iam/roles
Get all roles of the IoTHub
Query Parameters
- names: (string)
A comma separated list of role names to search for
HTTP status code 200
OK
Body
Media type: application/json
Type: array of userLib.RoleObject
Items: RoleObject
- name: required(string)
name of the role
- description: required(string)
description of the role
- scopes: required(array of userLib.ScopeName)
array of strings containing the names of the granted scopes
- created_at: required(integer)
timestamp of creation
Example:
[{
"name": "admin",
"description": "All rights granted",
"created_at": 1583222693041,
"scopes": [
"users",
"things",
"workflows",
"agents"
]
},{
"name": "assembly_line_A",
"description": "can manage things, workflows, and agents",
"created_at": 1583228575260,
"scopes": [
"things",
"workflows",
"agents"
]
},{
"name": "thing_creator",
"description": "can manage things",
"scopes": [
"things"
],
"created_at": 1568027832
},{
"name": "workflow_executor",
"description": "can manage workflows",
"scopes": [
"workflows"
],
"created_at": 1568027878
}]
post /iam/roles
Adds a role to the IoTHub
Body
Media type: application/json
Type: object
Properties- name: required(string)
name of the role or group
- description: required(string)
description of the role or group
Example:
{
"name": "admin-thing",
"description": "some description"
}
HTTP status code 200
OK
Body
Media type: application/json
Type: object
Properties- name: required(string)
name of the role
- description: required(string)
description of the role
- scopes: required(array of userLib.ScopeName)
array of strings containing the names of the granted scopes
- created_at: required(integer)
timestamp of creation
Example:
{
"name": "admin-thing",
"description": "some description",
"created_at": 1583228660246,
"scopes": []
}
Gets the role
Updates the role name and/or description at the IoTHub
Deletes the role from the IoTHub
get /iam/roles/{rolename}
Gets the role
URI Parameters
- rolename: required(string)
name of the role
HTTP status code 200
OK
Body
Media type: application/json
Type: object
Properties- name: required(string)
name of the role
- description: required(string)
description of the role
- scopes: required(array of userLib.ScopeName)
array of strings containing the names of the granted scopes
- created_at: required(integer)
timestamp of creation
Example:
{
"name": "admin",
"description": "All rights granted",
"created_at": 1583222693041,
"scopes": [
"users",
"things",
"workflows",
"agents"
]
}
patch /iam/roles/{rolename}
Updates the role name and/or description at the IoTHub
URI Parameters
- rolename: required(string)
name of the role
Body
Media type: application/json
Type: object
Properties- name: required(string)
name of the role or group
- description: required(string)
description of the role or group
Example:
{
"name": "admin-thing",
"description": "some description"
}
HTTP status code 200
OK
Body
Media type: application/json
Type: object
Properties- name: required(string)
name of the role
- description: required(string)
description of the role
- scopes: required(array of userLib.ScopeName)
array of strings containing the names of the granted scopes
- created_at: required(integer)
timestamp of creation
Example:
{
"name": "admin",
"description": "All rights granted",
"created_at": 1583222693041,
"scopes": [
"users",
"things",
"workflows",
"agents"
]
}
Gets the groups linked to the role
Adds groups to the role
put /iam/roles/{rolename}/groups
Removes groups from the role
put /iam/roles/{rolename}/groups/remove
Gets the users linked to the role
Adds users to the role
put /iam/roles/{rolename}/users
Removes users from the role
put /iam/roles/{rolename}/users/remove
Gets the scopes linked to the role
Updates a scope linked to the role
get /iam/roles/{rolename}/scopes
Gets the scopes linked to the role
URI Parameters
- rolename: required(string)
name of the role
HTTP status code 200
OK
Body
Media type: application/json
Type: array of object
Items: RoleScopeObject
- scope: required(string)
name of the scope
- enable_creation: (boolean)
permission to create
- enable_deletion: (boolean)
permission to delete
- is_admin: (boolean)
admin permissions
Example:
[
{
"scope": "users",
"enable_creation": true,
"enable_deletion": true,
"is_admin": true
},
{
"scope": "things",
"enable_creation": true,
"enable_deletion": true,
"is_admin": true
},
{
"scope": "workflows",
"enable_creation": true,
"enable_deletion": true,
"is_admin": true
},
{
"scope": "agents",
"enable_creation": true,
"enable_deletion": true,
"is_admin": true
}
]patch /iam/roles/{rolename}/scopes
Updates a scope linked to the role
URI Parameters
- rolename: required(string)
name of the role
Body
Media type: application/json
Type: object
Properties- scope: required(string)
name of the scope
- enable_creation: (boolean)
permission to create
- enable_deletion: (boolean)
permission to delete
- is_admin: (boolean)
admin permissions
Example:
{
"scope": "things",
"enable_creation": true,
"enable_deletion": true,
"is_admin": false
}
Gets the agents linked to the role
Adds agents to the role
Updates a scope linked to the role
get /iam/roles/{rolename}/scopes/agents
Gets the agents linked to the role
URI Parameters
- rolename: required(string)
name of the role
HTTP status code 200
OK
Body
Media type: application/json
Type: array of userLib.AgentsScope
Items: AgentsScope
- agent_name: required(string)
name of the agent
- enable_read: (boolean)
permission to read
- enable_write: (boolean)
permission to write
Example:
[
{
"agent_name": "s7-agent",
"enable_read": true,
"enable_write": true
},
{
"agent_name": "spider-agent",
"enable_read": true,
"enable_write": true
}
]
put /iam/roles/{rolename}/scopes/agents
Adds agents to the role
URI Parameters
- rolename: required(string)
name of the role
Body
Media type: application/json
Type: object
Properties- agent_name: required(string)
name of the agent
- enable_read: (boolean)
permission to read
- enable_write: (boolean)
permission to write
Example:
{
"agent_name": "s7-agent",
"enable_read": true,
"enable_write": true
}
HTTP status code 200
Body
Media type: application/json
Type: object
Properties- agent_name: required(string)
name of the agent
- enable_read: (boolean)
permission to read
- enable_write: (boolean)
permission to write
Example:
{
"agent_name": "s7-agent",
"enable_read": true,
"enable_write": true
}
HTTP status code 403
Forbidden, user credentials are not allowed for this request
HTTP status code 409
Conflict, the request could not be processed or it was already executed before
patch /iam/roles/{rolename}/scopes/agents
Updates a scope linked to the role
URI Parameters
- rolename: required(string)
name of the role
Body
Media type: application/json
Type: object
Properties- agent_name: required(string)
name of the agent
- enable_read: (boolean)
permission to read
- enable_write: (boolean)
permission to write
Example:
{
"agent_name": "s7-agent",
"enable_read": true,
"enable_write": true
}
HTTP status code 200
Body
Media type: application/json
Type: object
Properties- agent_name: required(string)
name of the agent
- enable_read: (boolean)
permission to read
- enable_write: (boolean)
permission to write
Example:
{
"agent_name": "s7-agent",
"enable_read": true,
"enable_write": true
}
HTTP status code 403
Forbidden, user credentials are not allowed for this request
List of agents to be removed
Gets the things linked to the role
Adds things to the role
Updates a scope linked to the role
get /iam/roles/{rolename}/scopes/things
Gets the things linked to the role
URI Parameters
- rolename: required(string)
name of the role
HTTP status code 200
OK
Body
Media type: application/json
Type: array of userLib.ThingsScope
Items: ThingsScope
- thing_id: required(string)
ID of the thing
- thing_name: required(string)
Name of the thing
- enable_read: (boolean)
permission to read
- enable_write: (boolean)
permission to write
- enable_configuration: (boolean)
permission to configure
- enable_actions: (boolean)
permission to execute actions
Example:
[
{
"thing_id": "4827858800541171713",
"thing_name": "Elco: Spider67mobile (020203226641164)",
"enable_read": true,
"enable_write": true,
"enable_configuration": false,
"enable_actions": false
},
{
"thing_id": "4827858800541171714",
"thing_name": "Elco: Spider67mobile (635877560360745)",
"enable_read": true,
"enable_write": true,
"enable_configuration": true,
"enable_actions": true
}
]
put /iam/roles/{rolename}/scopes/things
Adds things to the role
URI Parameters
- rolename: required(string)
name of the role
Body
Media type: application/json
Type: object
Properties- thing_id: required(string)
ID of the thing
- enable_read: (boolean)
permission to read
- enable_write: (boolean)
permission to write
- enable_configuration: (boolean)
permission to configure
- enable_actions: (boolean)
permission to execute actions
Example:
{
"thing_id": "4827858800541171713",
"enable_read": true,
"enable_write": true,
"enable_configuration": false,
"enable_actions": false
}
HTTP status code 200
Body
Media type: application/json
Type: object
Properties- thing_id: required(string)
ID of the thing
- thing_name: required(string)
Name of the thing
- enable_read: (boolean)
permission to read
- enable_write: (boolean)
permission to write
- enable_configuration: (boolean)
permission to configure
- enable_actions: (boolean)
permission to execute actions
Example:
{
"thing_id": "4827858800541171713",
"thing_name": "Elco: Spider67mobile (020203226641164)",
"enable_read": true,
"enable_write": true,
"enable_configuration": false,
"enable_actions": false
}
HTTP status code 403
Forbidden, user credentials are not allowed for this request
HTTP status code 409
Conflict, the request could not be processed or it was already executed before
patch /iam/roles/{rolename}/scopes/things
Updates a scope linked to the role
URI Parameters
- rolename: required(string)
name of the role
Body
Media type: application/json
Type: object
Properties- thing_id: required(string)
ID of the thing
- enable_read: (boolean)
permission to read
- enable_write: (boolean)
permission to write
- enable_configuration: (boolean)
permission to configure
- enable_actions: (boolean)
permission to execute actions
Example:
{
"thing_id": "4827858800541171713",
"enable_read": true,
"enable_write": true,
"enable_configuration": false,
"enable_actions": false
}
HTTP status code 200
Body
Media type: application/json
Type: object
Properties- thing_id: required(string)
ID of the thing
- thing_name: required(string)
Name of the thing
- enable_read: (boolean)
permission to read
- enable_write: (boolean)
permission to write
- enable_configuration: (boolean)
permission to configure
- enable_actions: (boolean)
permission to execute actions
Example:
{
"thing_id": "4827858800541171713",
"thing_name": "Elco: Spider67mobile (020203226641164)",
"enable_read": true,
"enable_write": true,
"enable_configuration": false,
"enable_actions": false
}
HTTP status code 403
Forbidden, user credentials are not allowed for this request
List of things to be removed
Gets the workflows linked to the role
Adds workflows to the role
Updates a workflow scope linked to the role
get /iam/roles/{rolename}/scopes/workflows
Gets the workflows linked to the role
URI Parameters
- rolename: required(string)
name of the role
HTTP status code 200
OK
Body
Media type: application/json
Type: array of userLib.WorkflowsScope
Items: WorkflowsScope
- workflow_id: required(integer)
ID of the workflow
- workflow_name: required(string)
Name of the workflow
- enable_read: (boolean)
permission to read
- enable_write: (boolean)
permission to write
- enable_execution: (boolean)
permission to execute the workflow
Example:
[
]
put /iam/roles/{rolename}/scopes/workflows
Adds workflows to the role
URI Parameters
- rolename: required(string)
name of the role
Body
Media type: application/json
Type: object
Properties- workflow_id: required(integer)
ID of the workflow
- enable_read: (boolean)
permission to read
- enable_write: (boolean)
permission to write
- enable_execution: (boolean)
permission to execute the workflow
Example:
{
"workflow_id" : 5
}
HTTP status code 200
Body
Media type: application/json
Type: object
Properties- workflow_id: required(integer)
ID of the workflow
- workflow_name: required(string)
Name of the workflow
- enable_read: (boolean)
permission to read
- enable_write: (boolean)
permission to write
- enable_execution: (boolean)
permission to execute the workflow
Example:
{
"workflow_id": 5,
"workflow_name": "observerProperties"
}
HTTP status code 403
Forbidden, user credentials are not allowed for this request
HTTP status code 409
Conflict, the request could not be processed or it was already executed before
patch /iam/roles/{rolename}/scopes/workflows
Updates a workflow scope linked to the role
URI Parameters
- rolename: required(string)
name of the role
Body
Media type: application/json
Type: object
Properties- workflow_id: required(integer)
ID of the workflow
- enable_read: (boolean)
permission to read
- enable_write: (boolean)
permission to write
- enable_execution: (boolean)
permission to execute the workflow
Example:
{
"workflow_id" : 5
}
HTTP status code 200
Body
Media type: application/json
Type: object
Properties- workflow_id: required(integer)
ID of the workflow
- workflow_name: required(string)
Name of the workflow
- enable_read: (boolean)
permission to read
- enable_write: (boolean)
permission to write
- enable_execution: (boolean)
permission to execute the workflow
Example:
{
"workflow_id": 5,
"workflow_name": "observerProperties"
}
HTTP status code 403
Forbidden, user credentials are not allowed for this request
List of workflows to be removed
Scope management
Available scopes (all scopes are currently auto-generated)
Gets all scopes of the IoTHub
get /iam/scopes
Gets all scopes of the IoTHub
Query Parameters
- names: (string)
A comma separated list of scopes names to search for
HTTP status code 200
OK
Body
Media type: application/json
Type: array of userLib.ScopeObject
Items: ScopeObject
- name: required(string)
name of the scope
- roles: (array of userLib.RoleName)
array of strings containing the names of the roles linked to the scope
Example:
[
{
"name": "agents",
"roles": [
"admin",
"assembly-line-A"
]
},
{
"name": "things",
"roles": [
"admin",
"assembly-line-A",
"production-line-B"
]
},
{
"name": "users",
"roles": [
"admin"
]
},
{
"name": "workflows",
"roles": [
"admin",
"production-line-B"
]
}
]
Gets the details of the scope
get /iam/scopes/{scopename}
Gets the details of the scope
URI Parameters
- scopename: required(string)
name of the scope
HTTP status code 200
Body
Media type: application/json
Type: object
Properties- name: required(string)
name of the scope
- roles: (array of userLib.RoleName)
array of strings containing the names of the roles linked to the scope
Example:
{
"name": "things",
"roles": [
"admin",
"assembly-line-A",
"production-line-B"
]
}
Things
Part of WoT API!
Requests for reading and manipulating things, properties, and actions.
Gets thing list
Adds a thing to the IoTHub
get /things
Gets thing list
Query Parameters
- id: (integer - minimum: 1)
Specifiy the things to be prefiltered with a list of ids. Can be mixed with name query.
Example:
?id=1&id=2 - name: (string)
Specifiy the things to be prefiltered with a list of names. Can be mixed with id query.
Example:
?name=thing_1&name=machine - small: (bool)
Outputs a compact json representation of the thing
Example:
?small=true
HTTP status code 200
OK
Body
Media type: application/json
Type: array of object
Items: ThingObject
- id: required(string)
ID of the thing
- title: required(string)
A human readable name of the property
Example:
Machine temperature - name: required(string)
Name of the thing
- state: required(object)
Example:
{ "reason": "", "status": "online" } - @type: required(array of string)
- description: (string)
- firmware: (string)
- identifiers: (array of string)
- href: required(string)
- links: required(object)
- properties: required(object)
- /^[\w-]+$/: required(object)
A data holding object for the thing.
- name: required(string)
Name of the property, must be unique inside the thing
Example:
temperature - title: (string)
A human readable name of the property
Example:
Machine temperature - description: (string)
Description of the property for a more detailed knowledge about the property.
Example:
Main temperature of the machine. Should be between 10°C and 70°C - unit: (string)
For numeric values an optional unit can be bound to the property
Example:
°C - readonly: required(boolean)
- type: required(string)
Type of the property can be string, boolean, (u)int[8,16,32,64], object and list
- minimum: (string)
Minimal number value of the property
- maximum: (string)
Maximal number value of the property
Example:
String:
A string property{ "type": "string", "name": "state", "title": "Machine state", "readonly": true } - name: required(string)
- /^[\w-]+$/: required(object)
- actions: required(object)
- /^[\w-]+$/: required(object)
- title: required(string)
Name of an action. Each action can have as many instances as it was called.
Example:
interval_update - description: (string)
- /^[\w-]+$/: (object)
Data of an action created by an action call.
- id: (string)
Id of an action instance
Example:
59a892fe-d0dd-4903-9ef9-a928417fa6fe - input: (object)
- output: (string)
- status: (string)
- timeCompleted: (string)
- timeRequested: (string)
Example:
{ "id": "59a892fe-d0dd-4903-9ef9-a928417fa6fe", "input": { "interval": 6000 }, "output": "published", "status": "SUCCESS", "timeCompleted": "2020-03-03T15:14:28.132+01:00", "timeRequested": "2020-03-03T15:14:28.131+01:00" } - id: (string)
- title: required(string)
- /^[\w-]+$/: required(object)
Examples:
SmallThings:
query ?small=true
[
{
"@type": "mqtt.generic",
"description": "",
"id": "14",
"name": "thing_ef2c86ee-e111-444c-aaeb-5bf3e14fe06c",
"state": {
"reason": "",
"status": "online"
},
"title": "Mqtt: Generic (287774826670966)"
}
]
FullThings:
query without "small" or "?small=false" parameter
[
{
"@type": [
"mqtt.generic"
],
"actions": {
"manual_configuration": {
"description": "Sends the configuration to the device manually",
"title": "Send configuration"
}
},
"configuration": {
"format": "json",
"identifier": "287774826670966"
},
"description": "",
"events": {
"changed_identifier": {
"@type": "IdentifierUpdateEvent",
"description": "Notifies if the device identifier was changed",
"href": "/things/14/events/changed_identifier",
"title": "Identifier"
},
"state": {
"@type": "",
"description": "Status updates for the thing",
"href": "/things/14/events/state",
"title": "Thing status events"
}
},
"href": "/things/14",
"id": 14,
"links": [
{
"href": "/things/14/properties",
"rel": "properties"
},
{
"href": "/things/14/actions",
"rel": "actions"
},
{
"href": "/things/14/events",
"rel": "events"
}
],
"name": "thing_ef2c86ee-e111-444c-aaeb-5bf3e14fe06c",
"properties": {
"active": {
"href": "/things/14/properties/active",
"readOnly": false,
"title": "",
"type": "boolean"
},
"humidity_range": {
"href": "/things/14/properties/humidity_range",
"readOnly": false,
"title": "",
"type": "object"
},
"humidity_sensor": {
"href": "/things/14/properties/humidity_sensor",
"readOnly": false,
"title": "",
"type": "float64"
}
},
"state": {
"reason": "",
"status": "online"
},
"title": "Mqtt: Generic (287774826670966)"
}
]
HTTP status code 404
not found in case of a query parameter is used for a thing which does not exist
post /things
Adds a thing to the IoTHub
Body
Media type: application/json
Type: object
Properties- name: required(string)
- title: required(string)
- @type: required(array of string)
- description: (string)
Example:
{
"name": "thing1",
"@type": [
"opc.ua"
],
"description": "",
"title": "opc ua server"
}
Gets the thing with the given ID or name
Update the thing with the given ID or name
Delete the thing with the given ID or name
get /things/{thing}
Gets the thing with the given ID or name
URI Parameters
- thing: required(string)
Name or Id of the thing
Examples:
Name:
Name of the thingMillingMachine1Id:
Id of the thing42
HTTP status code 200
OK
Body
Media type: application/json
Type: object
Properties- id: required(string)
ID of the thing
- title: required(string)
A human readable name of the property
Example:
Machine temperature - name: required(string)
Name of the thing
- state: required(object)
Example:
{ "reason": "", "status": "online" } - @type: required(array of string)
- description: (string)
- firmware: (string)
- identifiers: (array of string)
- href: required(string)
- links: required(object)
- properties
- actions: required(object)
- /^[\w-]+$/: required(object)
- title: required(string)
Name of an action. Each action can have as many instances as it was called.
Example:
interval_update - description: (string)
- /^[\w-]+$/: (object)
Data of an action created by an action call.
- id: (string)
Id of an action instance
Example:
59a892fe-d0dd-4903-9ef9-a928417fa6fe - input: (object)
- output: (string)
- status: (string)
- timeCompleted: (string)
- timeRequested: (string)
Example:
{ "id": "59a892fe-d0dd-4903-9ef9-a928417fa6fe", "input": { "interval": 6000 }, "output": "published", "status": "SUCCESS", "timeCompleted": "2020-03-03T15:14:28.132+01:00", "timeRequested": "2020-03-03T15:14:28.131+01:00" } - id: (string)
- title: required(string)
- /^[\w-]+$/: required(object)
Example:
{
"@type": [
"mqtt.generic"
],
"actions": {
"manual_configuration": {
"description": "Sends the configuration to the device manually",
"title": "Send configuration"
}
},
"configuration": {
"format": "json",
"identifier": "287774826670966"
},
"description": "",
"events": {
"changed_identifier": {
"@type": "IdentifierUpdateEvent",
"description": "Notifies if the device identifier was changed",
"href": "/things/14/events/changed_identifier",
"title": "Identifier"
},
"state": {
"@type": "",
"description": "Status updates for the thing",
"href": "/things/14/events/state",
"title": "Thing status events"
}
},
"href": "/things/14",
"id": 14,
"links": [
{
"href": "/things/14/properties",
"rel": "properties"
},
{
"href": "/things/14/actions",
"rel": "actions"
},
{
"href": "/things/14/events",
"rel": "events"
}
],
"name": "thing_ef2c86ee-e111-444c-aaeb-5bf3e14fe06c",
"properties": {
"active": {
"href": "/things/14/properties/active",
"readOnly": false,
"title": "",
"type": "boolean"
},
"humidity_range": {
"href": "/things/14/properties/humidity_range",
"readOnly": false,
"title": "",
"type": "object"
},
"humidity_sensor": {
"href": "/things/14/properties/humidity_sensor",
"readOnly": false,
"title": "",
"type": "float64"
}
},
"state": {
"reason": "",
"status": "online"
},
"title": "Mqtt: Generic (287774826670966)"
}
patch /things/{thing}
Update the thing with the given ID or name
URI Parameters
- thing: required(string)
Name or Id of the thing
Examples:
Name:
Name of the thingMillingMachine1Id:
Id of the thing42
Body
Media type: application/json
Type: object
Example:
{
"description": "Office"
}
HTTP status code 200
OK
Body
Media type: application/json
Type: object
Properties- id: required(string)
ID of the thing
- title: required(string)
A human readable name of the property
Example:
Machine temperature - name: required(string)
Name of the thing
- state: required(object)
Example:
{ "reason": "", "status": "online" } - @type: required(array of string)
- description: (string)
- firmware: (string)
- identifiers: (array of string)
- href: required(string)
- links: required(object)
- properties
- actions: required(object)
- /^[\w-]+$/: required(object)
- title: required(string)
Name of an action. Each action can have as many instances as it was called.
Example:
interval_update - description: (string)
- /^[\w-]+$/: (object)
Data of an action created by an action call.
- id: (string)
Id of an action instance
Example:
59a892fe-d0dd-4903-9ef9-a928417fa6fe - input: (object)
- output: (string)
- status: (string)
- timeCompleted: (string)
- timeRequested: (string)
Example:
{ "id": "59a892fe-d0dd-4903-9ef9-a928417fa6fe", "input": { "interval": 6000 }, "output": "published", "status": "SUCCESS", "timeCompleted": "2020-03-03T15:14:28.132+01:00", "timeRequested": "2020-03-03T15:14:28.131+01:00" } - id: (string)
- title: required(string)
- /^[\w-]+$/: required(object)
Example:
{
"@type": [
"mqtt.generic"
],
"actions": {
"manual_configuration": {
"description": "Sends the configuration to the device manually",
"title": "Send configuration"
}
},
"configuration": {
"format": "json",
"identifier": "287774826670966"
},
"description": "",
"events": {
"changed_identifier": {
"@type": "IdentifierUpdateEvent",
"description": "Notifies if the device identifier was changed",
"href": "/things/14/events/changed_identifier",
"title": "Identifier"
},
"state": {
"@type": "",
"description": "Status updates for the thing",
"href": "/things/14/events/state",
"title": "Thing status events"
}
},
"href": "/things/14",
"id": 14,
"links": [
{
"href": "/things/14/properties",
"rel": "properties"
},
{
"href": "/things/14/actions",
"rel": "actions"
},
{
"href": "/things/14/events",
"rel": "events"
}
],
"name": "thing_ef2c86ee-e111-444c-aaeb-5bf3e14fe06c",
"properties": {
"active": {
"href": "/things/14/properties/active",
"readOnly": false,
"title": "",
"type": "boolean"
},
"humidity_range": {
"href": "/things/14/properties/humidity_range",
"readOnly": false,
"title": "",
"type": "object"
},
"humidity_sensor": {
"href": "/things/14/properties/humidity_sensor",
"readOnly": false,
"title": "",
"type": "float64"
}
},
"state": {
"reason": "",
"status": "online"
},
"title": "Mqtt: Generic (287774826670966)"
}
Gets data of a certain property of a certain thing
Adds a property to a thing
get /things/{thing}/properties
Gets data of a certain property of a certain thing
URI Parameters
- thing: required(string)
Name or Id of the thing
Examples:
Name:
Name of the thingMillingMachine1Id:
Id of the thing42
HTTP status code 200
OK
Body
Media type: application/json
Type: object
Example:
{
"_configuration": {
"address": "192.168.0.10",
"port": 8080
},
"_state": {
"message": "the agent \"981be52b-1c0f-4303-aa73-da269b09d420\" is not connected or can not be found",
"status": "disconnected"
}
}post /things/{thing}/properties
Adds a property to a thing
URI Parameters
- thing: required(string)
Name or Id of the thing
Examples:
Name:
Name of the thingMillingMachine1Id:
Id of the thing42
Body
Media type: application/json
Type: object
Example:
{
"name": "ioport10",
"type": "boolean"
}
HTTP status code 200
OK
Body
Media type: application/json
Type: object
Example:
{
"thingId": "5764607523034234881",
"name": "test"
}
Requests getting list of properties of a thing
Writes the value of a property
Updates a metadata property of the property
Deletes the property from a thing
get /things/{thing}/properties/{propertyname}
Requests getting list of properties of a thing
URI Parameters
- thing: required(string)
Name or Id of the thing
Examples:
Name:
Name of the thingMillingMachine1Id:
Id of the thing42 - propertyname: required(string)
name of the requested property
HTTP status code 200
OK
Body
Media type: application/json
Type: object
Example:
{
"_configuration": {
"address": "192.168.0.10",
"agent": "981be52b-1c0f-4303-aa73-da269b09d420",
"labels": [
"bla"
],
"port": 8080
},
"_state": {
"message": "the agent \"981be52b-1c0f-4303-aa73-da269b09d420\" is not connected or can not be found",
"status": "disconnected"
}
}put /things/{thing}/properties/{propertyname}
Writes the value of a property
URI Parameters
- thing: required(string)
Name or Id of the thing
Examples:
Name:
Name of the thingMillingMachine1Id:
Id of the thing42 - propertyname: required(string)
name of the requested property
Body
Media type: application/json
Type: object
Example:
{
"light_switch_on": true
}
HTTP status code 200
OK
Body
Media type: application/json
Type: object
Example:
{
"thingId": "1",
"name": "light_switch_on"
}
patch /things/{thing}/properties/{propertyname}
Updates a metadata property of the property
URI Parameters
- thing: required(string)
Name or Id of the thing
Examples:
Name:
Name of the thingMillingMachine1Id:
Id of the thing42 - propertyname: required(string)
name of the requested property
Body
Media type: application/json
Type: object
Example:
{
"title": "light_switch_on",
"description": "State of the light switch"
}
HTTP status code 200
OK
Body
Media type: application/json
Type: object
Example:
{
"thingId": "1",
"name": "light_switch_on"
}
delete /things/{thing}/properties/{propertyname}
Gets actions from the thing
Requests the execution of an action of the thing
get /things/{thing}/actions
Gets actions from the thing
URI Parameters
- thing: required(string)
Name or Id of the thing
Examples:
Name:
Name of the thingMillingMachine1Id:
Id of the thing42
HTTP status code 200
OK
Body
Media type: application/json
Type: array of object
Example:
[
{
"send_configuration": {
"id": "59a892fe-d0dd-4903-9ef9-a928417fa6fe",
"output": "published",
"status": "SUCCESS",
"timeCompleted": "2020-03-02T10:58:51.293+01:00",
"timeRequested": "2020-03-02T10:58:51.292+01:00"
}
},
{
"interval_update": {
"id": "a1e9107b-4f5d-4cbe-a663-10e3bffa4552",
"input": {
"interval": 6000
},
"output": "published",
"status": "SUCCESS",
"timeCompleted": "2020-03-02T10:59:07.906+01:00",
"timeRequested": "2020-03-02T10:59:07.905+01:00"
}
},
{
"fota_update": {
"id": "1d2c4627-cc04-42a2-aefd-b86ec824ba57",
"output": "published",
"status": "SUCCESS",
"timeCompleted": "2020-03-02T10:59:21.563+01:00",
"timeRequested": "2020-03-02T10:59:21.562+01:00"
}
},
{
"logic_image": {
"id": "93713925-c9c1-423f-a492-c8920b035a57",
"input": {
"logic_list": [
"module_0.channel_0-(=)-module_1.channel_0",
"module_0.channel_1-(!=)-module_1.channel_1",
"module_4.channel_0-(>100)-module_1.channel_2",
"module_4.channel_1-(<100)-module_1.channel_3"
]
},
"output": "published",
"status": "SUCCESS",
"timeCompleted": "2020-03-02T10:59:37.081+01:00",
"timeRequested": "2020-03-02T10:59:37.081+01:00"
}
}
]post /things/{thing}/actions
Requests the execution of an action of the thing
URI Parameters
- thing: required(string)
Name or Id of the thing
Examples:
Name:
Name of the thingMillingMachine1Id:
Id of the thing42
Body
Media type: application/json
Type: object
Example:
{
"interval_update": {
"input": {
"interval": 6000
}
}
}HTTP status code 200
Body
Media type: application/json
Type: object
Example:
{
"interval_update": {
"href": "/v3/things/4827858800541171713/actions/interval_update/981be52b-1c0f-4303-aa73-da269b09d420",
"id": "981be52b-1c0f-4303-aa73-da269b09d420",
"input": {
"interval": 6000
},
"status": "pending"
}
}
HTTP status code 403
Forbidden, user credentials are not allowed for this request
Gets all actions with specified name from thing
Requests the execution of an action of the thing
get /things/{thing}/actions/{actionname}
Gets all actions with specified name from thing
URI Parameters
- thing: required(string)
Name or Id of the thing
Examples:
Name:
Name of the thingMillingMachine1Id:
Id of the thing42 - actionname: required(string)
Name of an action. Each action can have as many instances as it was called.
Example:
interval_update
HTTP status code 200
OK
Body
Media type: application/json
Type: array of wotLib.ActionResponseObject
Items: ActionResponseObject
- /^[\w-]+$/: required(object)
Data of an action created by an action call.
- id: (string)
Id of an action instance
Example:
59a892fe-d0dd-4903-9ef9-a928417fa6fe - input: (object)
- output: (string)
- status: (string)
- timeCompleted: (string)
- timeRequested: (string)
Example:
{ "id": "59a892fe-d0dd-4903-9ef9-a928417fa6fe", "input": { "interval": 6000 }, "output": "published", "status": "SUCCESS", "timeCompleted": "2020-03-03T15:14:28.132+01:00", "timeRequested": "2020-03-03T15:14:28.131+01:00" } - id: (string)
Example:
[
{
"interval_update": {
"id": "59a892fe-d0dd-4903-9ef9-a928417fa6fe",
"input": {
"interval": 6000
},
"output": "published",
"status": "SUCCESS",
"timeCompleted": "2020-03-03T15:14:28.132+01:00",
"timeRequested": "2020-03-03T15:14:28.131+01:00"
}
},
{
"interval_update": {
"id": "981be52b-1c0f-4303-aa73-da269b09d420",
"input": {
"interval": 6000
},
"output": "published",
"status": "SUCCESS",
"timeCompleted": "2020-03-03T15:16:32.859+01:00",
"timeRequested": "2020-03-03T15:16:32.858+01:00"
}
}
]
post /things/{thing}/actions/{actionname}
Requests the execution of an action of the thing
URI Parameters
- thing: required(string)
Name or Id of the thing
Examples:
Name:
Name of the thingMillingMachine1Id:
Id of the thing42 - actionname: required(string)
Name of an action. Each action can have as many instances as it was called.
Example:
interval_update
Body
Media type: application/json
Type: object
Example:
{
"interval_update": {
"input": {
"interval": 6000
}
}
}
HTTP status code 200
Body
Media type: application/json
Type: object
Example:
{
"interval_update": {
"href": "/v3/things/4827858800541171713/actions/interval_update/981be52b-1c0f-4303-aa73-da269b09d420",
"id": "981be52b-1c0f-4303-aa73-da269b09d420",
"input": {
"interval": 6000
},
"status": "pending"
}
}
HTTP status code 403
Forbidden, user credentials are not allowed for this request
Gets the action with specified id from the action list with the action name from thing
get /things/{thing}/actions/{actionname}/{actionid}
Gets the action with specified id from the action list with the action name from thing
URI Parameters
- thing: required(string)
Name or Id of the thing
Examples:
Name:
Name of the thingMillingMachine1Id:
Id of the thing42 - actionname: required(string)
Name of an action. Each action can have as many instances as it was called.
Example:
interval_update - actionid: required(string)
Id of an action instance
Example:
59a892fe-d0dd-4903-9ef9-a928417fa6fe
HTTP status code 200
OK
Body
Media type: application/json
Type: object
Properties- /^[\w-]+$/: required(object)
Data of an action created by an action call.
- id: (string)
Id of an action instance
Example:
59a892fe-d0dd-4903-9ef9-a928417fa6fe - input: (object)
- output: (string)
- status: (string)
- timeCompleted: (string)
- timeRequested: (string)
Example:
{ "id": "59a892fe-d0dd-4903-9ef9-a928417fa6fe", "input": { "interval": 6000 }, "output": "published", "status": "SUCCESS", "timeCompleted": "2020-03-03T15:14:28.132+01:00", "timeRequested": "2020-03-03T15:14:28.131+01:00" } - id: (string)
Example:
{
"interval_update": {
"id": "59a892fe-d0dd-4903-9ef9-a928417fa6fe",
"input": {
"interval": 6000
},
"output": "published",
"status": "SUCCESS",
"timeCompleted": "2020-03-03T15:14:28.132+01:00",
"timeRequested": "2020-03-03T15:14:28.131+01:00"
}
}
Gets the last up to ten raised events from each event type of the thing
get /things/{thing}/events
Gets the last up to ten raised events from each event type of the thing
URI Parameters
- thing: required(string)
Name or Id of the thing
Examples:
Name:
Name of the thingMillingMachine1Id:
Id of the thing42
HTTP status code 200
OK
Body
Media type: application/json
Type: array of object
Example:
[
{
"id":"53411c3d-8e4a-4d99-bb0d-9004ec202035",
"name":"status",
"data":"something",
"timestamp":1613462126327
},
{
"id":"e4963e8d-e1a8-44ae-9393-04d29ce5090c",
"name":"status",
"data":"something else",
"timestamp":1613462136327
},
{
"id":"f1963e8d-e1b8-44ae-9494-4d2546ce5030c",
"name":"temperature_alarm",
"data":123,
"timestamp":1613462136327
}
]
Gets the last up to ten raised events from the requested event type of the thing
get /things/{thing}/events/{eventname}
Gets the last up to ten raised events from the requested event type of the thing
URI Parameters
- thing: required(string)
Name or Id of the thing
Examples:
Name:
Name of the thingMillingMachine1Id:
Id of the thing42 - eventname: required(string)
Name of the event type, must be unique inside thing
Example:
status
HTTP status code 200
OK
Body
Media type: application/json
Type: array of object
Example:
[
{
"id":"53411c3d-8e4a-4d99-bb0d-9004ec202035",
"name":"status",
"data":"something",
"timestamp":1613462126327
},
{
"id":"e4963e8d-e1a8-44ae-9393-04d29ce5090c",
"name":"status",
"data":"something else",
"timestamp":1613462136327
}
]
Agents
Agents are used to bridge to different communication protocols and different edge controllers. Connects PLC's or external systems communicating via defined protocols like s7, OPC UA, ELCO-RFID or ModBus TCP
Gets the detailed information for an agent like connected PLCs
Adds an agent description to the IoTHub
get /agents
Gets the detailed information for an agent like connected PLCs
HTTP status code 200
OK
Body
Media type: application/json
Type: object
Properties- name: required(string)
name of the agent
- type: required(string)
type of the agent
- description: (string)
description of the agent
- token: required(string)
Unique token of the agent
Example:
{
"token": "59a892fe-d0dd-4903-9ef9-a928417fa6fe",
"name": "TransportS7",
"description": "S7 for the transport system",
"type": "siemens.s7"
}
post /agents
Adds an agent description to the IoTHub
Body
Media type: application/json
Type: object
Properties- name: required(string)
name of the agent
- type: required(string)
type of the agent
- description: (string)
description of the agent
Example:
{
"name": "TransportS7",
"type": "siemens.s7",
"description": "S7 for the transport system"
}HTTP status code 200
OK
Body
Media type: application/json
Type: object
Properties- name: required(string)
name of the agent
- type: required(string)
type of the agent
- description: (string)
description of the agent
- token: required(string)
Unique token of the agent
Example:
{
"token": "59a892fe-d0dd-4903-9ef9-a928417fa6fe",
"name": "TransportS7",
"description": "S7 for the transport system",
"type": "siemens.s7"
}
Gets the detailed information for an agent like connected PLCs
Updates the given agent
Deletes an agent from the IoTHub
get /agents/{agentname}
Gets the detailed information for an agent like connected PLCs
URI Parameters
- agentname: required(string)
name of the agent
HTTP status code 200
OK
Body
Media type: application/json
Type: object
Properties- name: required(string)
name of the agent
- type: required(string)
type of the agent
- description: (string)
description of the agent
- token: required(string)
Unique token of the agent
Example:
{
"token": "59a892fe-d0dd-4903-9ef9-a928417fa6fe",
"name": "TransportS7",
"description": "S7 for the transport system",
"type": "siemens.s7"
}
Triggers the Agent Token reroll.
post /agents/{agentname}/refreshtoken
Triggers the Agent Token reroll.
URI Parameters
- agentname: required(string)
HTTP status code 200
OK
Body
Media type: application/json
Type: object
Properties- name: required(string)
name of the agent
- type: required(string)
type of the agent
- description: (string)
description of the agent
- token: required(string)
Unique token of the agent
Example:
{
"token": "59a892fe-d0dd-4903-9ef9-a928417fa6fe",
"name": "TransportS7",
"description": "S7 for the transport system",
"type": "siemens.s7"
}
HTTP status code 404
Not found
Triggers the Enabling of an Agent.
post /agents/{agentname}/enable
Triggers the Enabling of an Agent.
Triggers the Disabling of an Agent.
post /agents/{agentname}/disable
Triggers the Disabling of an Agent.
Gets the assigned things of an agent
Adds the given things to the agent
get /agents/{agentname}/things
Gets the assigned things of an agent
URI Parameters
- agentname: required(string)
name of the agent
Query Parameters
- output: (string)
Specifies the output to three possible detail levels, defaults to ids.
Examples:
Names:
An array of thing names?output=namesFullOutput:
An Array of thing objects?output=fullIdsOnly:
An array of thing ids?output=ids
HTTP status code 200
OK
Body
Media type: application/json
Type: array
Examples:
FullOutput:
?output=full
[
{
"id": "2",
"name": "mqtt1"
},
{
"id": "3",
"name": "mqtt2",
"title": "my device",
"description": "My freezing machine"
}
]
IdsOnly:
?output=ids
[
"2",
"3"
]
NamesOnly:
?output=names (default)
[
"mqtt1",
"mqtt2"
]
Removes the given things from the agent
Gets the assigned Controller from an Agent
Assigns the given Controller to an Agent
Removes the assigned Controller from an Agent
Triggers the installation agent with the given credentials.
post /agents/{agentname}/controller/install
Triggers the installation agent with the given credentials.
URI Parameters
- agentname: required(string)
Body
Media type: application/json
Type: object
Example:
{
"username": "user",
"password": "superSecurePassword"
}
HTTP status code 200
OK
Body
Media type: application/json
Type: object
Example:
{
"agentId": "12",
"timestamp": "1620723120684",
"state": {
"status": "agentStatus",
"reason": "a reason why the status has changed/appeared"
}
}
Triggers the start of an Agent.
post /agents/{agentname}/controller/start
Triggers the start of an Agent.
URI Parameters
- agentname: required(string)
HTTP status code 200
OK
Body
Media type: application/json
Type: object
Example:
{
"agentId": "12",
"timestamp": "1620723120684",
"state": {
"status": "agentStatus",
"reason": "a reason why the status has changed/appeared"
}
}
Triggers the stop of an agent.
post /agents/{agentname}/controller/stop
Triggers the stop of an agent.
URI Parameters
- agentname: required(string)
HTTP status code 200
OK
Body
Media type: application/json
Type: object
Example:
{
"agentId": "12",
"timestamp": "1620723120684",
"state": {
"status": "agentStatus",
"reason": "a reason why the status has changed/appeared"
}
}
Triggers the restart of an agent.
post /agents/{agentname}/controller/restart
Triggers the restart of an agent.
URI Parameters
- agentname: required(string)
HTTP status code 200
OK
Body
Media type: application/json
Type: object
Example:
{
"agentId": "12",
"timestamp": "1620723120684",
"state": {
"status": "agentStatus",
"reason": "a reason why the status has changed/appeared"
}
}
Triggers the reset of an agent.
post /agents/{agentname}/controller/reset
Triggers the reset of an agent.
URI Parameters
- agentname: required(string)
HTTP status code 200
OK
Body
Media type: application/json
Type: object
Example:
{
"agentId": "12",
"timestamp": "1620723120684",
"state": {
"status": "agentStatus",
"reason": "a reason why the status has changed/appeared"
}
}
Retrieves the status of an agent from the assigned controller.
post /agents/{agentname}/controller/status
Retrieves the status of an agent from the assigned controller.
URI Parameters
- agentname: required(string)
HTTP status code 200
OK
Body
Media type: application/json
Type: object
Example:
{
"agentId": "12",
"timestamp": "1620723120684",
"state": {
"status": "agentStatus",
"reason": "a reason why the status has changed/appeared"
}
}
Retrieves the logs of an agent from the assigned controller.
post /agents/{agentname}/controller/logs
Retrieves the logs of an agent from the assigned controller.
URI Parameters
- agentname: required(string)
HTTP status code 200
OK
Body
Media type: application/json
Type: string
Example:
Version : latest
Commit : ffffffff
Built : 13.04.2021 12:45:55
11.05.2021 11:13:05.416 info Starting {"token": "asdddas", "address": ":1234"}
11.05.2021 11:13:05.416 info Connecting to the gateway {"address": ":1234"}
11.05.2021 11:13:05.421 info Connected to the gateway {"address": ":1234"}
Gets the config for an agent.
Updates the config of an Agent, needs to match schema of the agent.
get /agents/{agentname}/config
Gets the config for an agent.
URI Parameters
- agentname: required(string)
name of the agent
Query Parameters
- file: (boolean)
will deliver config as config.yml file instead of json if set true
Example:
?file=true
HTTP status code 200
OK
Body
Media type: application/json
Type: object
Example:
{
"debug": false,
"gateway": "localhost:9090",
"token": "308faf3d-1c8b-49f7-8484-2cd85f911d29"
}
patch /agents/{agentname}/config
Updates the config of an Agent, needs to match schema of the agent.
URI Parameters
- agentname: required(string)
name of the agent
Body
Media type: application/json
Type: object
Example:
{
"debug": false,
"gateway": "localhost:9090",
"token": "308faf3d-1c8b-49f7-8484-2cd85f911d29"
}
HTTP status code 204
No content
Gets controller by its Id.
get /agents/controllers/{id}
Gets controller by its Id.
URI Parameters
- id: required(string)
HTTP status code 200
OK
Body
Media type: application/json
Type: object
Properties- arch: required(string)
architecture of the host system, e.g. x86
- os: required(string)
operating system the controller is running on, e.g Windows
- name: required(string)
human readable name
- mac: required(string)
unique mac adress of the host
- id: required(string)
id
Example:
{
"arch": "arm",
"os": "macos",
"mac": "44-36-B5-27-3A-4F",
"id": "2",
"name": "controller two"
}
HTTP status code 404
Not found
Gets all available controllers.
get /agents/controllers
Gets all available controllers.
HTTP status code 200
OK
Body
Media type: application/json
Type: array of agencyLib.AgentController
Items: AgentController
- arch: required(string)
architecture of the host system, e.g. x86
- os: required(string)
operating system the controller is running on, e.g Windows
- name: required(string)
human readable name
- mac: required(string)
unique mac adress of the host
- id: required(string)
id
Example:
[
{
"arch": "arm",
"os": "macos",
"mac": "44-36-B5-27-3A-4F",
"id": "1",
"name": "controller two"
},
{
"arch": "amd64",
"os": "ubuntu",
"mac": "44-32-B5-27-3A-4E",
"id": "2",
"name": "controller two"
}
]
Historical data
Delivers the historical data of resources
Gets the historical data of a certain property.
get /history/{thing}/properties/{propname}
Gets the historical data of a certain property.
URI Parameters
- thing: required(string)
Name or Id of the thing
Examples:
Name:
Name of the thingMillingMachine1Id:
Id of the thing42 - propname: required(string)
name of the requested property
Query Parameters
- cursor: (string)
A hex value pointing to a page of values, a page contains the data inside one timespan. Mutually exclusive with the other parameters.
Example:
7b2273223a313537363635343031303038313434383039302c2274223a333630303030303030303030307d - start: (string)
Mutually exclusive with cursor, can be combined with timespan or end.
Examples:
Plain:
2006-01-02T15:04:05Z07:00Single:
Delivers the values starting and the given time and ending 1 hour later?start=2006-01-02T15%3A04%3A05Z07%3A00All:
Delivers the values between start and end. The timespan parameter is ignored, can be removed?start=2006-01-02T15%3A04%3A05Z07%3A00&end=2006-01-02T17%3A04%3A05Z07%3A00×pan=3hTimespan:
Delivers the values starting and the given time and ending 3 hours later?start=2006-01-02T15%3A04%3A05Z07%3A00×pan=3h - end: (string)
Mutually exclusive with cursor, can be combined with timespan or start.
Examples:
Plain:
A valid timestamp2006-01-02T15:04:05Z07:00Single:
Delivers the values ending and the given time and starting 1 hour earlier?end=2006-01-02T15%3A04%3A05Z07%3A00All:
Delivers the values between start and end. The timespan parameter is ignored, can be removed?start=2006-01-02T15%3A04%3A05Z07%3A00&end=2006-01-02T17%3A04%3A05Z07%3A00×pan=3hTimespan:
Delivers the values ending and the given time and starting 3 hours earlier?end=2006-01-02T15%3A04%3A05Z07%3A00timespan=3h - timespan: (string)
Get data inside the time span. The format is +/-??h??m??s??ms??us?ns, empty unit can be skipped. Mutually exclusive with cursor, can be combined with start or end.
Examples:
Plain:
Valid examples300ms, -1.5h, 2h45mSingle:
Delivers the values starting 3 hours earlier and ending now?timespan=3hStart:
Delivers the values starting and the given time and ending 3 hours later?start=2006-01-02T15%3A04%3A05Z07%3A00×pan=3hEnd:
Delivers the values ending and the given time and starting 3 hours earlier?end=2006-01-02T15%3A04%3A05Z07%3A00timespan=3h
HTTP status code 200
OK
Body
Media type: application/json
Type: object
Properties- id: required(string)
ID of the thing
- name: required(string)
A human readable name of the property
Example:
Machine temperature - items: required(array of historyLib.HistoryData)
Items: HistoryData
- processtime: required(number)
Time of arrival in the IoTHub
Example:
1576653143561 - changetime: required(number)
Time of change of the value, default is processtime
Example:
1576653143561 - value: required(any)
Example:
{ "processtime": 1576653143561, "changetime": 1576653143561, "value": 6 } - processtime: required(number)
- query: required(object)
Contains the resolved time span of the query resulting in the response
- start: required(string)
Timestamp of the begin of the history data set
Example:
2019-12-18T07:26:50.08144809+01:00 - end: required(string)
Timestamp of the end of the history data set
Example:
2019-12-18T08:26:50.08144809+01:00
- start: required(string)
- cursor: required(object)
A collection of cursors to navigate back in time and ahead
- after: required(string)
Cursor for the values following this data set
Example:
7b2273223a313537363635343031303038313434383039302c2274223a333630303030303030303030307d - before: required(string)
Cursor for the values before this data set
Example:
7b2273223a313537363635343031303038313434383039302c2274223a333630303030303030303030307d
- after: required(string)
Example:
{
"id": "2",
"name": "vol",
"items":[
{
"processtime": 1576653143561,
"changetime": 1576653143561,
"value": 6
},
{
"processtime": 1576653144561,
"changetime": 1576653144561,
"value": 8
}
],
"query": {
"start": "2019-12-18T07:26:50.08144809+01:00",
"end": "2019-12-18T08:26:50.08144809+01:00"
},
"cursor": {
"after": "7b2273223a313537363635343031303038313434383039302c2274223a333630303030303030303030307d",
"before": "7b2273223a313537363634363831303038313434383039302c2274223a333630303030303030303030307d"
}
}Workflows
Add, delete, deliver, show, maintain, start, stop workflows and receiving log messages of them.
Gets all workflows added to the IoTHub
Adds a workflow to the IoTHub
get /workflows
Gets all workflows added to the IoTHub
HTTP status code 200
OK
Body
Media type: application/json
Type: array of object
Items: WorkflowObject
- name: required(string)
- version: (string)
- description: (string)
- main: (string)
- scripts: (object)
- config: (object)
- id: required(integer)
ID of the workflow
- running: required(boolean)
- debug: required(boolean)
- version: required(integer)
- secret: (string)
- id: required(integer)
- keywords: (array of string)
- author: (string)
- license: (string)
post /workflows
Adds a workflow to the IoTHub
Body
Media type: application/json
Type: object
Properties- name: required(string)
- version: (string)
- description: (string)
- main: (string)
- scripts: (object)
- config: (object)
- id: required(integer)
ID of the workflow
- running: required(boolean)
- debug: required(boolean)
- version: required(integer)
- secret: (string)
- id: required(integer)
- keywords: (array of string)
- author: (string)
- license: (string)
Example:
{
"name": "s7test",
"version": "1.0.0",
"description": "A script which runs in the workflow module of the IoT Hub.",
"main": "script.js",
"scripts": {},
"config": {
"id": 1,
"running": false,
"debug": false,
"version": 0
},
"keywords": [
"IoT Hub Script",
"WoT Scripting"
],
"author": "unknown",
"license": "ISC"
}
HTTP status code 201
OK
Body
Media type: application/json
Type: object
Properties- name: required(string)
- version: (string)
- description: (string)
- main: (string)
- scripts: (object)
- config: (object)
- id: required(integer)
ID of the workflow
- running: required(boolean)
- debug: required(boolean)
- version: required(integer)
- secret: (string)
- id: required(integer)
- keywords: (array of string)
- author: (string)
- license: (string)
Example:
{
"name": "s7test",
"version": "1.0.0",
"description": "A script which runs in the workflow module of the IoT Hub.",
"main": "script.js",
"scripts": {},
"config": {
"id": 1,
"running": false,
"debug": false,
"version": 0
},
"keywords": [
"IoT Hub Script",
"WoT Scripting"
],
"author": "unknown",
"license": "ISC"
}
Gets the workflow
Updates the workflow at the IoTHub
Deletes the workflow from the IoTHub
get /workflows/{workflowid}
Gets the workflow
URI Parameters
- workflowid: required(integer)
ID of the workflow
HTTP status code 200
OK
Body
Media type: application/json
Type: object
Properties- name: required(string)
- version: (string)
- description: (string)
- main: (string)
- scripts: (object)
- config: (object)
- id: required(integer)
ID of the workflow
- running: required(boolean)
- debug: required(boolean)
- version: required(integer)
- secret: (string)
- id: required(integer)
- keywords: (array of string)
- author: (string)
- license: (string)
Example:
{
"name": "s7test",
"version": "1.0.0",
"description": "A script which runs in the workflow module of the IoT Hub.",
"main": "script.js",
"scripts": {},
"config": {
"id": 1,
"running": false,
"debug": false,
"version": 0
},
"keywords": [
"IoT Hub Script",
"WoT Scripting"
],
"author": "unknown",
"license": "ISC"
}
put /workflows/{workflowid}
Updates the workflow at the IoTHub
URI Parameters
- workflowid: required(integer)
ID of the workflow
Body
Media type: application/json
Type: object
Properties- name: required(string)
- version: (string)
- description: (string)
- main: (string)
- scripts: (object)
- config: (object)
- id: required(integer)
ID of the workflow
- running: required(boolean)
- debug: required(boolean)
- version: required(integer)
- secret: (string)
- id: required(integer)
- keywords: (array of string)
- author: (string)
- license: (string)
Example:
{
"name": "s7test",
"version": "1.0.0",
"description": "A script which runs in the workflow module of the IoT Hub.",
"main": "script.js",
"scripts": {},
"config": {
"id": 1,
"running": false,
"debug": false,
"version": 0
},
"keywords": [
"IoT Hub Script",
"WoT Scripting"
],
"author": "unknown",
"license": "ISC"
}
HTTP status code 200
OK
Body
Media type: application/json
Type: object
Properties- name: required(string)
- version: (string)
- description: (string)
- main: (string)
- scripts: (object)
- config: (object)
- id: required(integer)
ID of the workflow
- running: required(boolean)
- debug: required(boolean)
- version: required(integer)
- secret: (string)
- id: required(integer)
- keywords: (array of string)
- author: (string)
- license: (string)
Example:
{
"name": "s7test",
"version": "1.0.0",
"description": "A script which runs in the workflow module of the IoT Hub.",
"main": "script.js",
"scripts": {},
"config": {
"id": 1,
"running": false,
"debug": false,
"version": 0
},
"keywords": [
"IoT Hub Script",
"WoT Scripting"
],
"author": "unknown",
"license": "ISC"
}
Starts the workflow if not already running
Stops the workflow if running
Restarts the workflow if not already running
Starts the workflow if not already running
Get the workflows script(s)
Updates the given workflow
put /workflows/{workflowid}/script
Updates the given workflow
URI Parameters
- workflowid: required(integer)
ID of the workflow
Body
Media type: application/json
Type: object
Properties- name: required(string)
- version: (string)
- description: (string)
- main: (string)
- scripts: (object)
- config: (object)
- id: required(integer)
ID of the workflow
- running: required(boolean)
- debug: required(boolean)
- version: required(integer)
- secret: (string)
- id: required(integer)
- keywords: (array of string)
- author: (string)
- license: (string)
Example:
{
"name": "s7test",
"version": "1.0.0",
"description": "A script which runs in the workflow module of the IoT Hub.",
"main": "script.js",
"scripts": {},
"config": {
"id": 1,
"running": false,
"debug": false,
"version": 0
},
"keywords": [
"IoT Hub Script",
"WoT Scripting"
],
"author": "unknown",
"license": "ISC"
}
HTTP status code 200
OK
Alarm Configuration
Create, observe, control and acknowledge alarms, manage reactions to alarms.
Gets the full alarm list
get /alarms/config
Gets the full alarm list
HTTP status code 200
OK
Body
Media type: application/json
Type: array of object
Items: AlarmConfigurationResponse
- id: required(number)
Unique id of the alarm
- description: (string)
A meaningful description of the alarm
Example:
Alarm raises when machine temperature becomes too hot - type: required(string)
Type of the alarm, one of "standard", "average" or "novalue"
- title: required(string)
A meaningful title of the alarm
- level: required(string)
An user defined level of the alarm. The level is domain specific and part of the unique triplet (thing id, property name and level).
- severity: required(string)
One of the values "info", "warning", "error" and "critical". Classifies the alarm in a common way regarding its impact.
- property: required(object)
Combines the two identifiers to make the property unique for the whole IoTHub.
- thing: required(number)
- name: required(string)
Name of the property, must be unique inside the thing
Example:
temperature
Example:
{ "thing": 541171713, "name": "temperature" } - limit: required(object)
Definition of the limit result to (de)activate an alarm
- operator: required(string)
Depending on the type of the property one of "EQ" (equals, all), "NE" (not equals, all), "GT" (greater than, numeric), "GE" (greater or equals, numeric), "LT" (less than, numeric) or "LE" (less or equals, numeric).
- value: required(union of string or number or boolean)
The value of the property to trigger the alarm
- deadband: (number)
Range around the trigger value (value +/- deadband/2) the alarm is triggered if inside. For (GT,GE) operators the alarm is triggered at (value + deadband/2) and untriggered below (value - deadband/2), for (LE,LT) operators vice versa. A negative value reverses the this logic. This is the calculated value based on deadband_input. On an integer based property, this is rounded to the nearest integer, on float based numbers to two digit precision.
Examples:
IntegerExample:
An integer deadband when used with an alarm that watches an integer type property.42NumberExample:
An floating point deadband when used with an alarm that watches a float type property.42.35 - deadband_input: (string)
Range around the trigger value (value +/- deadband/2) the alarm is triggered if inside. For (GT,GE) operators the alarm is triggered at (value + deadband/2) and untriggered below (value - deadband/2), for (LE,LT) operators vice versa. A negative value reverses the this logic. An relative percentage value can be used as well, which calculates the needed range autonomously.
Examples:
AbsoluteValue:
An absolute value for the range500.1PercentageValue:
Needs to be a percentage value between [0.00,100.00]%50,31% - observetime: (number)
Time in seconds a value must be in triggered range to activate the alarm. 0 or not given activates the alarm immediately.
Examples:
Numeric:
Limit for a typical numeric property{ "operator": "GT", "value": 70, "deadband": 2.5, "observetime": 5 }String:
Limit for a typical string property{ "operator": "NE", "value": "running", "observetime": 2 }Boolean:
Limit for a typical boolean property{ "operator": "EQ", "value": false, "observetime": 10 } - operator: required(string)
- reactions: required(array of alarmLib.AlarmReaction)
A list of reactions assigned to the alarm.
Items: AlarmReaction
- id: required(number)
A system managed unique id for the reaction.
- title: (string)
Name of the reaction
- description: (string)
Description of the reaction.
Example:
Sends an e-mail to the CEO. - type: required(string)
Type of the reaction, currently supported are "email" (send an e-mail) and "hook" (send a web hook message)
- config: (union of alarmLib.EMailTemplate or alarmLib.WebHookTemplate)
An object with the values overriding the values in the template
Examples:
EMailToOtherReceiver:
Sends the email from the template to a different address.{ "address": "ceo@company.com" }OtherMessageToWebhook:
Uses the template for all information, but replaces the content.{ "content": "A different message to the web hook." } - alarm_id: required(number)
A reference to the alarm id
- template_id: (number)
Reference to the template containing the default configuration
- interval: (object)
The definition of sending intervals and repetitions for the reaction. The items are numbers with a time unit (seconds, minutes or hours). If the alarm is deactivated earlier the executions are stopped. If the interval is not defined the reaction will be executed only once right after activation.
- initial: (array of string)
Ordered array of time values for single execution.
- repeat: (string)
Time value for repeating execution.
Examples:
SimpleRepeat:
Repeats the reaction every 5 minutes.{ "repeat": "5m" }IncreasingInterval:
Executes the reaction after 5 seconds, 10 minutes and 1 hour.{ "initial": ["5s", "10m", "1h"] }IntervalAndRepeat:
Executes the reaction after 5 seconds, 10 minutes and repeats afterwards every 30 minutes.{ "initial": ["5s", "10m"], "repeat": "30m" } - initial: (array of string)
Examples:
Email:
An e-mail reaction{ "id": 437, "title": "Mail to boss", "description": "Sends a mail to the boss", "type": "email", "config": { "subject" : "Machine is overheating", "message" : "The temperature of the machine reaches a critical value.", "address" : "boss@company.com" }, "alarm_id": 4, "interval": { "initial": ["5m", "15m"], "repeat": "30m" } }WebHook:
A web hook reaction{ "id": 443, "title": "Message to the messenger", "description": "Sends a message to the messenger", "type": "hook", "config": { "url": "http://messenger/error", "http_method": "POST", "content": "The machine temperature is too high", "header": { "authorization": "BEARER ey45af=", "content_type": "plain/text", "user_agent": "john_doe" } }, "alarm_id": 4, "interval": { "repeat": "10m" } } - id: required(number)
- enabled: required(boolean)
If true the alarm is enabled and reacts on value changes of the observed property, if set to false the alarm will be not activated.
Gets the list of alarms associates with properties of the given thing.
get /alarms/config/things/{thing}
Gets the list of alarms associates with properties of the given thing.
URI Parameters
- thing: required(string)
Name or Id of the thing
Examples:
Name:
Name of the thingMillingMachine1Id:
Id of the thing42
HTTP status code 200
OK
Body
Media type: application/json
Type: array of object
Items: AlarmConfigurationResponse
- id: required(number)
Unique id of the alarm
- description: (string)
A meaningful description of the alarm
Example:
Alarm raises when machine temperature becomes too hot - type: required(string)
Type of the alarm, one of "standard", "average" or "novalue"
- title: required(string)
A meaningful title of the alarm
- level: required(string)
An user defined level of the alarm. The level is domain specific and part of the unique triplet (thing id, property name and level).
- severity: required(string)
One of the values "info", "warning", "error" and "critical". Classifies the alarm in a common way regarding its impact.
- property: required(object)
Combines the two identifiers to make the property unique for the whole IoTHub.
- thing: required(number)
- name: required(string)
Name of the property, must be unique inside the thing
Example:
temperature
Example:
{ "thing": 541171713, "name": "temperature" } - limit: required(object)
Definition of the limit result to (de)activate an alarm
- operator: required(string)
Depending on the type of the property one of "EQ" (equals, all), "NE" (not equals, all), "GT" (greater than, numeric), "GE" (greater or equals, numeric), "LT" (less than, numeric) or "LE" (less or equals, numeric).
- value: required(union of string or number or boolean)
The value of the property to trigger the alarm
- deadband: (number)
Range around the trigger value (value +/- deadband/2) the alarm is triggered if inside. For (GT,GE) operators the alarm is triggered at (value + deadband/2) and untriggered below (value - deadband/2), for (LE,LT) operators vice versa. A negative value reverses the this logic. This is the calculated value based on deadband_input. On an integer based property, this is rounded to the nearest integer, on float based numbers to two digit precision.
Examples:
IntegerExample:
An integer deadband when used with an alarm that watches an integer type property.42NumberExample:
An floating point deadband when used with an alarm that watches a float type property.42.35 - deadband_input: (string)
Range around the trigger value (value +/- deadband/2) the alarm is triggered if inside. For (GT,GE) operators the alarm is triggered at (value + deadband/2) and untriggered below (value - deadband/2), for (LE,LT) operators vice versa. A negative value reverses the this logic. An relative percentage value can be used as well, which calculates the needed range autonomously.
Examples:
AbsoluteValue:
An absolute value for the range500.1PercentageValue:
Needs to be a percentage value between [0.00,100.00]%50,31% - observetime: (number)
Time in seconds a value must be in triggered range to activate the alarm. 0 or not given activates the alarm immediately.
Examples:
Numeric:
Limit for a typical numeric property{ "operator": "GT", "value": 70, "deadband": 2.5, "observetime": 5 }String:
Limit for a typical string property{ "operator": "NE", "value": "running", "observetime": 2 }Boolean:
Limit for a typical boolean property{ "operator": "EQ", "value": false, "observetime": 10 } - operator: required(string)
- reactions: required(array of alarmLib.AlarmReaction)
A list of reactions assigned to the alarm.
Items: AlarmReaction
- id: required(number)
A system managed unique id for the reaction.
- title: (string)
Name of the reaction
- description: (string)
Description of the reaction.
Example:
Sends an e-mail to the CEO. - type: required(string)
Type of the reaction, currently supported are "email" (send an e-mail) and "hook" (send a web hook message)
- config: (union of alarmLib.EMailTemplate or alarmLib.WebHookTemplate)
An object with the values overriding the values in the template
Examples:
EMailToOtherReceiver:
Sends the email from the template to a different address.{ "address": "ceo@company.com" }OtherMessageToWebhook:
Uses the template for all information, but replaces the content.{ "content": "A different message to the web hook." } - alarm_id: required(number)
A reference to the alarm id
- template_id: (number)
Reference to the template containing the default configuration
- interval: (object)
The definition of sending intervals and repetitions for the reaction. The items are numbers with a time unit (seconds, minutes or hours). If the alarm is deactivated earlier the executions are stopped. If the interval is not defined the reaction will be executed only once right after activation.
- initial: (array of string)
Ordered array of time values for single execution.
- repeat: (string)
Time value for repeating execution.
Examples:
SimpleRepeat:
Repeats the reaction every 5 minutes.{ "repeat": "5m" }IncreasingInterval:
Executes the reaction after 5 seconds, 10 minutes and 1 hour.{ "initial": ["5s", "10m", "1h"] }IntervalAndRepeat:
Executes the reaction after 5 seconds, 10 minutes and repeats afterwards every 30 minutes.{ "initial": ["5s", "10m"], "repeat": "30m" } - initial: (array of string)
Examples:
Email:
An e-mail reaction{ "id": 437, "title": "Mail to boss", "description": "Sends a mail to the boss", "type": "email", "config": { "subject" : "Machine is overheating", "message" : "The temperature of the machine reaches a critical value.", "address" : "boss@company.com" }, "alarm_id": 4, "interval": { "initial": ["5m", "15m"], "repeat": "30m" } }WebHook:
A web hook reaction{ "id": 443, "title": "Message to the messenger", "description": "Sends a message to the messenger", "type": "hook", "config": { "url": "http://messenger/error", "http_method": "POST", "content": "The machine temperature is too high", "header": { "authorization": "BEARER ey45af=", "content_type": "plain/text", "user_agent": "john_doe" } }, "alarm_id": 4, "interval": { "repeat": "10m" } } - id: required(number)
- enabled: required(boolean)
If true the alarm is enabled and reacts on value changes of the observed property, if set to false the alarm will be not activated.
HTTP status code 404
If the thing with the given id or name was not found
Gets the list of alarms associates with the property of the given thing.
Adds an alarm to the property of the thing
get /alarms/config/things/{thing}/properties/{property}
Gets the list of alarms associates with the property of the given thing.
URI Parameters
- thing: required(string)
Name or Id of the thing
Examples:
Name:
Name of the thingMillingMachine1Id:
Id of the thing42 - property: required(string)
Name of the property, must be unique inside the thing
Example:
temperature
HTTP status code 200
OK
Body
Media type: application/json
Type: array of object
Items: AlarmConfigurationResponse
- id: required(number)
Unique id of the alarm
- description: (string)
A meaningful description of the alarm
Example:
Alarm raises when machine temperature becomes too hot - type: required(string)
Type of the alarm, one of "standard", "average" or "novalue"
- title: required(string)
A meaningful title of the alarm
- level: required(string)
An user defined level of the alarm. The level is domain specific and part of the unique triplet (thing id, property name and level).
- severity: required(string)
One of the values "info", "warning", "error" and "critical". Classifies the alarm in a common way regarding its impact.
- property: required(object)
Combines the two identifiers to make the property unique for the whole IoTHub.
- thing: required(number)
- name: required(string)
Name of the property, must be unique inside the thing
Example:
temperature
Example:
{ "thing": 541171713, "name": "temperature" } - limit: required(object)
Definition of the limit result to (de)activate an alarm
- operator: required(string)
Depending on the type of the property one of "EQ" (equals, all), "NE" (not equals, all), "GT" (greater than, numeric), "GE" (greater or equals, numeric), "LT" (less than, numeric) or "LE" (less or equals, numeric).
- value: required(union of string or number or boolean)
The value of the property to trigger the alarm
- deadband: (number)
Range around the trigger value (value +/- deadband/2) the alarm is triggered if inside. For (GT,GE) operators the alarm is triggered at (value + deadband/2) and untriggered below (value - deadband/2), for (LE,LT) operators vice versa. A negative value reverses the this logic. This is the calculated value based on deadband_input. On an integer based property, this is rounded to the nearest integer, on float based numbers to two digit precision.
Examples:
IntegerExample:
An integer deadband when used with an alarm that watches an integer type property.42NumberExample:
An floating point deadband when used with an alarm that watches a float type property.42.35 - deadband_input: (string)
Range around the trigger value (value +/- deadband/2) the alarm is triggered if inside. For (GT,GE) operators the alarm is triggered at (value + deadband/2) and untriggered below (value - deadband/2), for (LE,LT) operators vice versa. A negative value reverses the this logic. An relative percentage value can be used as well, which calculates the needed range autonomously.
Examples:
AbsoluteValue:
An absolute value for the range500.1PercentageValue:
Needs to be a percentage value between [0.00,100.00]%50,31% - observetime: (number)
Time in seconds a value must be in triggered range to activate the alarm. 0 or not given activates the alarm immediately.
Examples:
Numeric:
Limit for a typical numeric property{ "operator": "GT", "value": 70, "deadband": 2.5, "observetime": 5 }String:
Limit for a typical string property{ "operator": "NE", "value": "running", "observetime": 2 }Boolean:
Limit for a typical boolean property{ "operator": "EQ", "value": false, "observetime": 10 } - operator: required(string)
- reactions: required(array of alarmLib.AlarmReaction)
A list of reactions assigned to the alarm.
Items: AlarmReaction
- id: required(number)
A system managed unique id for the reaction.
- title: (string)
Name of the reaction
- description: (string)
Description of the reaction.
Example:
Sends an e-mail to the CEO. - type: required(string)
Type of the reaction, currently supported are "email" (send an e-mail) and "hook" (send a web hook message)
- config: (union of alarmLib.EMailTemplate or alarmLib.WebHookTemplate)
An object with the values overriding the values in the template
Examples:
EMailToOtherReceiver:
Sends the email from the template to a different address.{ "address": "ceo@company.com" }OtherMessageToWebhook:
Uses the template for all information, but replaces the content.{ "content": "A different message to the web hook." } - alarm_id: required(number)
A reference to the alarm id
- template_id: (number)
Reference to the template containing the default configuration
- interval: (object)
The definition of sending intervals and repetitions for the reaction. The items are numbers with a time unit (seconds, minutes or hours). If the alarm is deactivated earlier the executions are stopped. If the interval is not defined the reaction will be executed only once right after activation.
- initial: (array of string)
Ordered array of time values for single execution.
- repeat: (string)
Time value for repeating execution.
Examples:
SimpleRepeat:
Repeats the reaction every 5 minutes.{ "repeat": "5m" }IncreasingInterval:
Executes the reaction after 5 seconds, 10 minutes and 1 hour.{ "initial": ["5s", "10m", "1h"] }IntervalAndRepeat:
Executes the reaction after 5 seconds, 10 minutes and repeats afterwards every 30 minutes.{ "initial": ["5s", "10m"], "repeat": "30m" } - initial: (array of string)
Examples:
Email:
An e-mail reaction{ "id": 437, "title": "Mail to boss", "description": "Sends a mail to the boss", "type": "email", "config": { "subject" : "Machine is overheating", "message" : "The temperature of the machine reaches a critical value.", "address" : "boss@company.com" }, "alarm_id": 4, "interval": { "initial": ["5m", "15m"], "repeat": "30m" } }WebHook:
A web hook reaction{ "id": 443, "title": "Message to the messenger", "description": "Sends a message to the messenger", "type": "hook", "config": { "url": "http://messenger/error", "http_method": "POST", "content": "The machine temperature is too high", "header": { "authorization": "BEARER ey45af=", "content_type": "plain/text", "user_agent": "john_doe" } }, "alarm_id": 4, "interval": { "repeat": "10m" } } - id: required(number)
- enabled: required(boolean)
If true the alarm is enabled and reacts on value changes of the observed property, if set to false the alarm will be not activated.
HTTP status code 404
If the property or the thing with the given id was not found
post /alarms/config/things/{thing}/properties/{property}
Adds an alarm to the property of the thing
URI Parameters
- thing: required(string)
Name or Id of the thing
Examples:
Name:
Name of the thingMillingMachine1Id:
Id of the thing42 - property: required(string)
Name of the property, must be unique inside the thing
Example:
temperature
Body
Media type: application/json
Type: object
Properties- title: required(string)
A meaningful title of the alarm
- description: (string)
A meaningful description of the alarm
Example:
Alarm raises when machine temperature becomes too hot - type: required(string)
Type of the alarm, one of "standard", "average" or "novalue"
- level: required(string)
An user defined level of the alarm. The level is domain specific and part of the unique triplet (thing id, property name and level).
- severity: required(string)
One of the values "info", "warning", "error" and "critical". Classifies the alarm in a common way regarding its impact.
- limit: required(object)
Definition of the limit to (de)activate an alarm
- operator: required(string)
Depending on the type of the property one of "EQ" (equals, all), "NE" (not equals, all), "GT" (greater than, numeric), "GE" (greater or equals, numeric), "LT" (less than, numeric) or "LE" (less or equals, numeric).
- value: required(union of string or number or boolean)
The value of the property to trigger the alarm
- deadband_input: (string)
Range around the trigger value (value +/- deadband/2) the alarm is triggered if inside. For (GT,GE) operators the alarm is triggered at (value + deadband/2) and untriggered below (value - deadband/2), for (LE,LT) operators vice versa. A negative value reverses the this logic. An relative percentage value can be used as well, which calculates the needed range autonomously.
Examples:
AbsoluteValue:
An absolute value for the range500.1PercentageValue:
Needs to be a percentage value between [0.00,100.00]%50,31% - observetime: (number)
Time in seconds a value must be in triggered range to activate the alarm. 0 or not given activates the alarm immediately.
Examples:
Numeric:
Limit for a typical numeric property{ "operator": "GT", "value": 70, "deadband": 2.5, "observetime": 5 }String:
Limit for a typical string property{ "operator": "NE", "value": "running", "observetime": 2 }Boolean:
Limit for a typical boolean property{ "operator": "EQ", "value": false, "observetime": 10 } - operator: required(string)
Example:
{
"title": "Machine overheating",
"description": "Alarm raises when machine temperature becomes too hot",
"type": "standard",
"level": "high",
"severity": "warning",
"limit": {
"operator": "GT",
"value": "70",
"deadband_input": "2.5",
"observetime": 5
}
}
HTTP status code 200
OK
Body
Media type: application/json
Type: object
Properties- id: required(number)
Unique id of the alarm
- description: (string)
A meaningful description of the alarm
Example:
Alarm raises when machine temperature becomes too hot - type: required(string)
Type of the alarm, one of "standard", "average" or "novalue"
- title: required(string)
A meaningful title of the alarm
- level: required(string)
An user defined level of the alarm. The level is domain specific and part of the unique triplet (thing id, property name and level).
- severity: required(string)
One of the values "info", "warning", "error" and "critical". Classifies the alarm in a common way regarding its impact.
- property: required(object)
Combines the two identifiers to make the property unique for the whole IoTHub.
- thing: required(number)
- name: required(string)
Name of the property, must be unique inside the thing
Example:
temperature
Example:
{ "thing": 541171713, "name": "temperature" } - limit: required(object)
Definition of the limit result to (de)activate an alarm
- operator: required(string)
Depending on the type of the property one of "EQ" (equals, all), "NE" (not equals, all), "GT" (greater than, numeric), "GE" (greater or equals, numeric), "LT" (less than, numeric) or "LE" (less or equals, numeric).
- value: required(union of string or number or boolean)
The value of the property to trigger the alarm
- deadband: (number)
Range around the trigger value (value +/- deadband/2) the alarm is triggered if inside. For (GT,GE) operators the alarm is triggered at (value + deadband/2) and untriggered below (value - deadband/2), for (LE,LT) operators vice versa. A negative value reverses the this logic. This is the calculated value based on deadband_input. On an integer based property, this is rounded to the nearest integer, on float based numbers to two digit precision.
Examples:
IntegerExample:
An integer deadband when used with an alarm that watches an integer type property.42NumberExample:
An floating point deadband when used with an alarm that watches a float type property.42.35 - deadband_input: (string)
Range around the trigger value (value +/- deadband/2) the alarm is triggered if inside. For (GT,GE) operators the alarm is triggered at (value + deadband/2) and untriggered below (value - deadband/2), for (LE,LT) operators vice versa. A negative value reverses the this logic. An relative percentage value can be used as well, which calculates the needed range autonomously.
Examples:
AbsoluteValue:
An absolute value for the range500.1PercentageValue:
Needs to be a percentage value between [0.00,100.00]%50,31% - observetime: (number)
Time in seconds a value must be in triggered range to activate the alarm. 0 or not given activates the alarm immediately.
Examples:
Numeric:
Limit for a typical numeric property{ "operator": "GT", "value": 70, "deadband": 2.5, "observetime": 5 }String:
Limit for a typical string property{ "operator": "NE", "value": "running", "observetime": 2 }Boolean:
Limit for a typical boolean property{ "operator": "EQ", "value": false, "observetime": 10 } - operator: required(string)
- reactions: required(array of alarmLib.AlarmReaction)
A list of reactions assigned to the alarm.
Items: AlarmReaction
- id: required(number)
A system managed unique id for the reaction.
- title: (string)
Name of the reaction
- description: (string)
Description of the reaction.
Example:
Sends an e-mail to the CEO. - type: required(string)
Type of the reaction, currently supported are "email" (send an e-mail) and "hook" (send a web hook message)
- config: (union of alarmLib.EMailTemplate or alarmLib.WebHookTemplate)
An object with the values overriding the values in the template
Examples:
EMailToOtherReceiver:
Sends the email from the template to a different address.{ "address": "ceo@company.com" }OtherMessageToWebhook:
Uses the template for all information, but replaces the content.{ "content": "A different message to the web hook." } - alarm_id: required(number)
A reference to the alarm id
- template_id: (number)
Reference to the template containing the default configuration
- interval: (object)
The definition of sending intervals and repetitions for the reaction. The items are numbers with a time unit (seconds, minutes or hours). If the alarm is deactivated earlier the executions are stopped. If the interval is not defined the reaction will be executed only once right after activation.
- initial: (array of string)
Ordered array of time values for single execution.
- repeat: (string)
Time value for repeating execution.
Examples:
SimpleRepeat:
Repeats the reaction every 5 minutes.{ "repeat": "5m" }IncreasingInterval:
Executes the reaction after 5 seconds, 10 minutes and 1 hour.{ "initial": ["5s", "10m", "1h"] }IntervalAndRepeat:
Executes the reaction after 5 seconds, 10 minutes and repeats afterwards every 30 minutes.{ "initial": ["5s", "10m"], "repeat": "30m" } - initial: (array of string)
Examples:
Email:
An e-mail reaction{ "id": 437, "title": "Mail to boss", "description": "Sends a mail to the boss", "type": "email", "config": { "subject" : "Machine is overheating", "message" : "The temperature of the machine reaches a critical value.", "address" : "boss@company.com" }, "alarm_id": 4, "interval": { "initial": ["5m", "15m"], "repeat": "30m" } }WebHook:
A web hook reaction{ "id": 443, "title": "Message to the messenger", "description": "Sends a message to the messenger", "type": "hook", "config": { "url": "http://messenger/error", "http_method": "POST", "content": "The machine temperature is too high", "header": { "authorization": "BEARER ey45af=", "content_type": "plain/text", "user_agent": "john_doe" } }, "alarm_id": 4, "interval": { "repeat": "10m" } } - id: required(number)
- enabled: required(boolean)
If true the alarm is enabled and reacts on value changes of the observed property, if set to false the alarm will be not activated.
Example:
{
"id": 4,
"title": "Machine overheating",
"description": "Alarm raises when machine temperature becomes too hot",
"type": "standard",
"level": "high",
"severity": "warning",
"property": {
"thing": 4827858800541171713,
"name": "temperature"
},
"limit": {
"operator": "GT",
"value": "70",
"deadband": 2.5,
"deadband_input": "2.5",
"observetime": 5
},
"reactions": [
{
"id": 437,
"title": "Mail to boss",
"description": "Sends a mail to the boss",
"type": "email",
"config": {
"address": "smith@company.com"
},
"alarm_id": 4,
"template_id": 2,
"interval": {
"initial": ["30s", "1m", "5m"],
"repeat": "30m"
}
},
{
"id": 443,
"title": "Urgent message",
"description": "Sends a message to the messenger channel urgent",
"type": "hook",
"config": {
"url": "http://messanger/urgent",
"content": "Machine is overheating"
},
"alarm_id": 4,
"template_id": 1,
"interval": {
"repeat": "5m"
}
}
],
"enabled": true
}
HTTP status code 404
If the alarm with the given id was not found
Gets the alarm with given level associates with the property of the given thing.
Update the alarm with given level associates with the property of the given thing.
Delete the alarm with given level associates with the property of the given thing.
get /alarms/config/things/{thing}/properties/{property}/{level}
Gets the alarm with given level associates with the property of the given thing.
URI Parameters
- thing: required(string)
Name or Id of the thing
Examples:
Name:
Name of the thingMillingMachine1Id:
Id of the thing42 - property: required(string)
Name of the property, must be unique inside the thing
Example:
temperature - level: required(string)
An user defined level of the alarm. The level is domain specific and part of the unique triplet (thing id, property name and level).
HTTP status code 200
OK
Body
Media type: application/json
Type: object
Properties- id: required(number)
Unique id of the alarm
- description: (string)
A meaningful description of the alarm
Example:
Alarm raises when machine temperature becomes too hot - type: required(string)
Type of the alarm, one of "standard", "average" or "novalue"
- title: required(string)
A meaningful title of the alarm
- level: required(string)
An user defined level of the alarm. The level is domain specific and part of the unique triplet (thing id, property name and level).
- severity: required(string)
One of the values "info", "warning", "error" and "critical". Classifies the alarm in a common way regarding its impact.
- property: required(object)
Combines the two identifiers to make the property unique for the whole IoTHub.
- thing: required(number)
- name: required(string)
Name of the property, must be unique inside the thing
Example:
temperature
Example:
{ "thing": 541171713, "name": "temperature" } - limit: required(object)
Definition of the limit result to (de)activate an alarm
- operator: required(string)
Depending on the type of the property one of "EQ" (equals, all), "NE" (not equals, all), "GT" (greater than, numeric), "GE" (greater or equals, numeric), "LT" (less than, numeric) or "LE" (less or equals, numeric).
- value: required(union of string or number or boolean)
The value of the property to trigger the alarm
- deadband: (number)
Range around the trigger value (value +/- deadband/2) the alarm is triggered if inside. For (GT,GE) operators the alarm is triggered at (value + deadband/2) and untriggered below (value - deadband/2), for (LE,LT) operators vice versa. A negative value reverses the this logic. This is the calculated value based on deadband_input. On an integer based property, this is rounded to the nearest integer, on float based numbers to two digit precision.
Examples:
IntegerExample:
An integer deadband when used with an alarm that watches an integer type property.42NumberExample:
An floating point deadband when used with an alarm that watches a float type property.42.35 - deadband_input: (string)
Range around the trigger value (value +/- deadband/2) the alarm is triggered if inside. For (GT,GE) operators the alarm is triggered at (value + deadband/2) and untriggered below (value - deadband/2), for (LE,LT) operators vice versa. A negative value reverses the this logic. An relative percentage value can be used as well, which calculates the needed range autonomously.
Examples:
AbsoluteValue:
An absolute value for the range500.1PercentageValue:
Needs to be a percentage value between [0.00,100.00]%50,31% - observetime: (number)
Time in seconds a value must be in triggered range to activate the alarm. 0 or not given activates the alarm immediately.
Examples:
Numeric:
Limit for a typical numeric property{ "operator": "GT", "value": 70, "deadband": 2.5, "observetime": 5 }String:
Limit for a typical string property{ "operator": "NE", "value": "running", "observetime": 2 }Boolean:
Limit for a typical boolean property{ "operator": "EQ", "value": false, "observetime": 10 } - operator: required(string)
- reactions: required(array of alarmLib.AlarmReaction)
A list of reactions assigned to the alarm.
Items: AlarmReaction
- id: required(number)
A system managed unique id for the reaction.
- title: (string)
Name of the reaction
- description: (string)
Description of the reaction.
Example:
Sends an e-mail to the CEO. - type: required(string)
Type of the reaction, currently supported are "email" (send an e-mail) and "hook" (send a web hook message)
- config: (union of alarmLib.EMailTemplate or alarmLib.WebHookTemplate)
An object with the values overriding the values in the template
Examples:
EMailToOtherReceiver:
Sends the email from the template to a different address.{ "address": "ceo@company.com" }OtherMessageToWebhook:
Uses the template for all information, but replaces the content.{ "content": "A different message to the web hook." } - alarm_id: required(number)
A reference to the alarm id
- template_id: (number)
Reference to the template containing the default configuration
- interval: (object)
The definition of sending intervals and repetitions for the reaction. The items are numbers with a time unit (seconds, minutes or hours). If the alarm is deactivated earlier the executions are stopped. If the interval is not defined the reaction will be executed only once right after activation.
- initial: (array of string)
Ordered array of time values for single execution.
- repeat: (string)
Time value for repeating execution.
Examples:
SimpleRepeat:
Repeats the reaction every 5 minutes.{ "repeat": "5m" }IncreasingInterval:
Executes the reaction after 5 seconds, 10 minutes and 1 hour.{ "initial": ["5s", "10m", "1h"] }IntervalAndRepeat:
Executes the reaction after 5 seconds, 10 minutes and repeats afterwards every 30 minutes.{ "initial": ["5s", "10m"], "repeat": "30m" } - initial: (array of string)
Examples:
Email:
An e-mail reaction{ "id": 437, "title": "Mail to boss", "description": "Sends a mail to the boss", "type": "email", "config": { "subject" : "Machine is overheating", "message" : "The temperature of the machine reaches a critical value.", "address" : "boss@company.com" }, "alarm_id": 4, "interval": { "initial": ["5m", "15m"], "repeat": "30m" } }WebHook:
A web hook reaction{ "id": 443, "title": "Message to the messenger", "description": "Sends a message to the messenger", "type": "hook", "config": { "url": "http://messenger/error", "http_method": "POST", "content": "The machine temperature is too high", "header": { "authorization": "BEARER ey45af=", "content_type": "plain/text", "user_agent": "john_doe" } }, "alarm_id": 4, "interval": { "repeat": "10m" } } - id: required(number)
- enabled: required(boolean)
If true the alarm is enabled and reacts on value changes of the observed property, if set to false the alarm will be not activated.
Example:
{
"id": 4,
"title": "Machine overheating",
"description": "Alarm raises when machine temperature becomes too hot",
"type": "standard",
"level": "high",
"severity": "warning",
"property": {
"thing": 4827858800541171713,
"name": "temperature"
},
"limit": {
"operator": "GT",
"value": "70",
"deadband": 2.5,
"deadband_input": "2.5",
"observetime": 5
},
"reactions": [
{
"id": 437,
"title": "Mail to boss",
"description": "Sends a mail to the boss",
"type": "email",
"config": {
"address": "smith@company.com"
},
"alarm_id": 4,
"template_id": 2,
"interval": {
"initial": ["30s", "1m", "5m"],
"repeat": "30m"
}
},
{
"id": 443,
"title": "Urgent message",
"description": "Sends a message to the messenger channel urgent",
"type": "hook",
"config": {
"url": "http://messanger/urgent",
"content": "Machine is overheating"
},
"alarm_id": 4,
"template_id": 1,
"interval": {
"repeat": "5m"
}
}
],
"enabled": true
}
HTTP status code 404
If the alarm identified via the property and the alarm level was not found.
patch /alarms/config/things/{thing}/properties/{property}/{level}
Update the alarm with given level associates with the property of the given thing.
URI Parameters
- thing: required(string)
Name or Id of the thing
Examples:
Name:
Name of the thingMillingMachine1Id:
Id of the thing42 - property: required(string)
Name of the property, must be unique inside the thing
Example:
temperature - level: required(string)
An user defined level of the alarm. The level is domain specific and part of the unique triplet (thing id, property name and level).
Body
Media type: application/json
Type: object
Properties- title: required(string)
A meaningful title of the alarm
- description: (string)
A meaningful description of the alarm
Example:
Alarm raises when machine temperature becomes too hot - type: required(string)
Type of the alarm, one of "standard", "average" or "novalue"
- level: required(string)
An user defined level of the alarm. The level is domain specific and part of the unique triplet (thing id, property name and level).
- severity: required(string)
One of the values "info", "warning", "error" and "critical". Classifies the alarm in a common way regarding its impact.
- limit: required(object)
Definition of the limit to (de)activate an alarm
- operator: required(string)
Depending on the type of the property one of "EQ" (equals, all), "NE" (not equals, all), "GT" (greater than, numeric), "GE" (greater or equals, numeric), "LT" (less than, numeric) or "LE" (less or equals, numeric).
- value: required(union of string or number or boolean)
The value of the property to trigger the alarm
- deadband_input: (string)
Range around the trigger value (value +/- deadband/2) the alarm is triggered if inside. For (GT,GE) operators the alarm is triggered at (value + deadband/2) and untriggered below (value - deadband/2), for (LE,LT) operators vice versa. A negative value reverses the this logic. An relative percentage value can be used as well, which calculates the needed range autonomously.
Examples:
AbsoluteValue:
An absolute value for the range500.1PercentageValue:
Needs to be a percentage value between [0.00,100.00]%50,31% - observetime: (number)
Time in seconds a value must be in triggered range to activate the alarm. 0 or not given activates the alarm immediately.
Examples:
Numeric:
Limit for a typical numeric property{ "operator": "GT", "value": 70, "deadband": 2.5, "observetime": 5 }String:
Limit for a typical string property{ "operator": "NE", "value": "running", "observetime": 2 }Boolean:
Limit for a typical boolean property{ "operator": "EQ", "value": false, "observetime": 10 } - operator: required(string)
Example:
{
"title": "Machine overheating",
"description": "Alarm raises when machine temperature becomes too hot",
"type": "standard",
"level": "high",
"severity": "warning",
"limit": {
"operator": "GT",
"value": "70",
"deadband_input": "2.5",
"observetime": 5
}
}
HTTP status code 200
OK
Body
Media type: application/json
Type: object
Properties- id: required(number)
Unique id of the alarm
- description: (string)
A meaningful description of the alarm
Example:
Alarm raises when machine temperature becomes too hot - type: required(string)
Type of the alarm, one of "standard", "average" or "novalue"
- title: required(string)
A meaningful title of the alarm
- level: required(string)
An user defined level of the alarm. The level is domain specific and part of the unique triplet (thing id, property name and level).
- severity: required(string)
One of the values "info", "warning", "error" and "critical". Classifies the alarm in a common way regarding its impact.
- property: required(object)
Combines the two identifiers to make the property unique for the whole IoTHub.
- thing: required(number)
- name: required(string)
Name of the property, must be unique inside the thing
Example:
temperature
Example:
{ "thing": 541171713, "name": "temperature" } - limit: required(object)
Definition of the limit result to (de)activate an alarm
- operator: required(string)
Depending on the type of the property one of "EQ" (equals, all), "NE" (not equals, all), "GT" (greater than, numeric), "GE" (greater or equals, numeric), "LT" (less than, numeric) or "LE" (less or equals, numeric).
- value: required(union of string or number or boolean)
The value of the property to trigger the alarm
- deadband: (number)
Range around the trigger value (value +/- deadband/2) the alarm is triggered if inside. For (GT,GE) operators the alarm is triggered at (value + deadband/2) and untriggered below (value - deadband/2), for (LE,LT) operators vice versa. A negative value reverses the this logic. This is the calculated value based on deadband_input. On an integer based property, this is rounded to the nearest integer, on float based numbers to two digit precision.
Examples:
IntegerExample:
An integer deadband when used with an alarm that watches an integer type property.42NumberExample:
An floating point deadband when used with an alarm that watches a float type property.42.35 - deadband_input: (string)
Range around the trigger value (value +/- deadband/2) the alarm is triggered if inside. For (GT,GE) operators the alarm is triggered at (value + deadband/2) and untriggered below (value - deadband/2), for (LE,LT) operators vice versa. A negative value reverses the this logic. An relative percentage value can be used as well, which calculates the needed range autonomously.
Examples:
AbsoluteValue:
An absolute value for the range500.1PercentageValue:
Needs to be a percentage value between [0.00,100.00]%50,31% - observetime: (number)
Time in seconds a value must be in triggered range to activate the alarm. 0 or not given activates the alarm immediately.
Examples:
Numeric:
Limit for a typical numeric property{ "operator": "GT", "value": 70, "deadband": 2.5, "observetime": 5 }String:
Limit for a typical string property{ "operator": "NE", "value": "running", "observetime": 2 }Boolean:
Limit for a typical boolean property{ "operator": "EQ", "value": false, "observetime": 10 } - operator: required(string)
- reactions: required(array of alarmLib.AlarmReaction)
A list of reactions assigned to the alarm.
Items: AlarmReaction
- id: required(number)
A system managed unique id for the reaction.
- title: (string)
Name of the reaction
- description: (string)
Description of the reaction.
Example:
Sends an e-mail to the CEO. - type: required(string)
Type of the reaction, currently supported are "email" (send an e-mail) and "hook" (send a web hook message)
- config: (union of alarmLib.EMailTemplate or alarmLib.WebHookTemplate)
An object with the values overriding the values in the template
Examples:
EMailToOtherReceiver:
Sends the email from the template to a different address.{ "address": "ceo@company.com" }OtherMessageToWebhook:
Uses the template for all information, but replaces the content.{ "content": "A different message to the web hook." } - alarm_id: required(number)
A reference to the alarm id
- template_id: (number)
Reference to the template containing the default configuration
- interval: (object)
The definition of sending intervals and repetitions for the reaction. The items are numbers with a time unit (seconds, minutes or hours). If the alarm is deactivated earlier the executions are stopped. If the interval is not defined the reaction will be executed only once right after activation.
- initial: (array of string)
Ordered array of time values for single execution.
- repeat: (string)
Time value for repeating execution.
Examples:
SimpleRepeat:
Repeats the reaction every 5 minutes.{ "repeat": "5m" }IncreasingInterval:
Executes the reaction after 5 seconds, 10 minutes and 1 hour.{ "initial": ["5s", "10m", "1h"] }IntervalAndRepeat:
Executes the reaction after 5 seconds, 10 minutes and repeats afterwards every 30 minutes.{ "initial": ["5s", "10m"], "repeat": "30m" } - initial: (array of string)
Examples:
Email:
An e-mail reaction{ "id": 437, "title": "Mail to boss", "description": "Sends a mail to the boss", "type": "email", "config": { "subject" : "Machine is overheating", "message" : "The temperature of the machine reaches a critical value.", "address" : "boss@company.com" }, "alarm_id": 4, "interval": { "initial": ["5m", "15m"], "repeat": "30m" } }WebHook:
A web hook reaction{ "id": 443, "title": "Message to the messenger", "description": "Sends a message to the messenger", "type": "hook", "config": { "url": "http://messenger/error", "http_method": "POST", "content": "The machine temperature is too high", "header": { "authorization": "BEARER ey45af=", "content_type": "plain/text", "user_agent": "john_doe" } }, "alarm_id": 4, "interval": { "repeat": "10m" } } - id: required(number)
- enabled: required(boolean)
If true the alarm is enabled and reacts on value changes of the observed property, if set to false the alarm will be not activated.
Example:
{
"id": 4,
"title": "Machine overheating",
"description": "Alarm raises when machine temperature becomes too hot",
"type": "standard",
"level": "high",
"severity": "warning",
"property": {
"thing": 4827858800541171713,
"name": "temperature"
},
"limit": {
"operator": "GT",
"value": "70",
"deadband": 2.5,
"deadband_input": "2.5",
"observetime": 5
},
"reactions": [
{
"id": 437,
"title": "Mail to boss",
"description": "Sends a mail to the boss",
"type": "email",
"config": {
"address": "smith@company.com"
},
"alarm_id": 4,
"template_id": 2,
"interval": {
"initial": ["30s", "1m", "5m"],
"repeat": "30m"
}
},
{
"id": 443,
"title": "Urgent message",
"description": "Sends a message to the messenger channel urgent",
"type": "hook",
"config": {
"url": "http://messanger/urgent",
"content": "Machine is overheating"
},
"alarm_id": 4,
"template_id": 1,
"interval": {
"repeat": "5m"
}
}
],
"enabled": true
}
HTTP status code 404
If the alarm identified via the property and the alarm level was not found.
delete /alarms/config/things/{thing}/properties/{property}/{level}
Delete the alarm with given level associates with the property of the given thing.
URI Parameters
- thing: required(string)
Name or Id of the thing
Examples:
Name:
Name of the thingMillingMachine1Id:
Id of the thing42 - property: required(string)
Name of the property, must be unique inside the thing
Example:
temperature - level: required(string)
An user defined level of the alarm. The level is domain specific and part of the unique triplet (thing id, property name and level).
Enables the alarm given by the property and the level
post /alarms/config/things/{thing}/properties/{property}/{level}/enable
Enables the alarm given by the property and the level
URI Parameters
- thing: required(string)
Name or Id of the thing
Examples:
Name:
Name of the thingMillingMachine1Id:
Id of the thing42 - property: required(string)
Name of the property, must be unique inside the thing
Example:
temperature - level: required(string)
An user defined level of the alarm. The level is domain specific and part of the unique triplet (thing id, property name and level).
Body
Media type: application/json
Type: any
Example:
{}Disables the alarm given by the property and the level
post /alarms/config/things/{thing}/properties/{property}/{level}/disable
Disables the alarm given by the property and the level
URI Parameters
- thing: required(string)
Name or Id of the thing
Examples:
Name:
Name of the thingMillingMachine1Id:
Id of the thing42 - property: required(string)
Name of the property, must be unique inside the thing
Example:
temperature - level: required(string)
An user defined level of the alarm. The level is domain specific and part of the unique triplet (thing id, property name and level).
Body
Media type: application/json
Type: any
Example:
{}Gets the list of reactions of the alarm identified via the property and alarm level
Adds a reaction to the alarm identified via the property and alarm level
get /alarms/config/things/{thing}/properties/{property}/{level}/reactions
Gets the list of reactions of the alarm identified via the property and alarm level
URI Parameters
- thing: required(string)
Name or Id of the thing
Examples:
Name:
Name of the thingMillingMachine1Id:
Id of the thing42 - property: required(string)
Name of the property, must be unique inside the thing
Example:
temperature - level: required(string)
An user defined level of the alarm. The level is domain specific and part of the unique triplet (thing id, property name and level).
HTTP status code 200
OK
Body
Media type: application/json
Type: array of alarmLib.AlarmReaction
Items: AlarmReaction
- id: required(number)
A system managed unique id for the reaction.
- title: (string)
Name of the reaction
- description: (string)
Description of the reaction.
Example:
Sends an e-mail to the CEO. - type: required(string)
Type of the reaction, currently supported are "email" (send an e-mail) and "hook" (send a web hook message)
- config: (union of alarmLib.EMailTemplate or alarmLib.WebHookTemplate)
An object with the values overriding the values in the template
Examples:
EMailToOtherReceiver:
Sends the email from the template to a different address.{ "address": "ceo@company.com" }OtherMessageToWebhook:
Uses the template for all information, but replaces the content.{ "content": "A different message to the web hook." } - alarm_id: required(number)
A reference to the alarm id
- template_id: (number)
Reference to the template containing the default configuration
- interval: (object)
The definition of sending intervals and repetitions for the reaction. The items are numbers with a time unit (seconds, minutes or hours). If the alarm is deactivated earlier the executions are stopped. If the interval is not defined the reaction will be executed only once right after activation.
- initial: (array of string)
Ordered array of time values for single execution.
- repeat: (string)
Time value for repeating execution.
Examples:
SimpleRepeat:
Repeats the reaction every 5 minutes.{ "repeat": "5m" }IncreasingInterval:
Executes the reaction after 5 seconds, 10 minutes and 1 hour.{ "initial": ["5s", "10m", "1h"] }IntervalAndRepeat:
Executes the reaction after 5 seconds, 10 minutes and repeats afterwards every 30 minutes.{ "initial": ["5s", "10m"], "repeat": "30m" } - initial: (array of string)
HTTP status code 404
If the alarm identified via the property and alarm level was not found.
post /alarms/config/things/{thing}/properties/{property}/{level}/reactions
Adds a reaction to the alarm identified via the property and alarm level
URI Parameters
- thing: required(string)
Name or Id of the thing
Examples:
Name:
Name of the thingMillingMachine1Id:
Id of the thing42 - property: required(string)
Name of the property, must be unique inside the thing
Example:
temperature - level: required(string)
An user defined level of the alarm. The level is domain specific and part of the unique triplet (thing id, property name and level).
Body
Media type: application/json
Type: object
Properties- title: (string)
Name of the reaction
- description: (string)
Description of the reaction.
Example:
Sends an e-mail to the CEO. - type: required(string)
Type of the reaction, currently supported are "email" (send an e-mail) and "hook" (send a web hook message)
- config: (union of alarmLib.EMailTemplate or alarmLib.WebHookTemplate)
An object with the values overriding the values in the template
Examples:
EMailToOtherReceiver:
Sends the email from the template to a different address.{ "address": "ceo@company.com" }OtherMessageToWebhook:
Uses the template for all information, but replaces the content.{ "content": "A different message to the web hook." } - alarm_id: required(number)
A reference to the alarm id
- template_id: (number)
Reference to the template containing the default configuration
- interval: (object)
The definition of sending intervals and repetitions for the reaction. The items are numbers with a time unit (seconds, minutes or hours). If the alarm is deactivated earlier the executions are stopped. If the interval is not defined the reaction will be executed only once right after activation.
- initial: (array of string)
Ordered array of time values for single execution.
- repeat: (string)
Time value for repeating execution.
Examples:
SimpleRepeat:
Repeats the reaction every 5 minutes.{ "repeat": "5m" }IncreasingInterval:
Executes the reaction after 5 seconds, 10 minutes and 1 hour.{ "initial": ["5s", "10m", "1h"] }IntervalAndRepeat:
Executes the reaction after 5 seconds, 10 minutes and repeats afterwards every 30 minutes.{ "initial": ["5s", "10m"], "repeat": "30m" } - initial: (array of string)
Examples:
Email:
An e-mail reaction
{
"title": "Mail to boss",
"description": "Sends a mail to the boss",
"type": "email",
"config": {
"address": "john_doe@company.com"
},
"alarm_id": 4,
"template_id": 2,
"interval": {
"initial": ["5m", "15m"],
"repeat": "30m"
}
}
WebHook:
A web hook reaction
{
"title": "Message to the messenger",
"description": "Sends a message to the messenger",
"type": "hook",
"config": {
"content": "The machine temperature is too high"
},
"alarm_id": 4,
"template_id": 1,
"interval": {
"repeat": "10m"
}
}
HTTP status code 200
OK
Body
Media type: application/json
Type: object
Properties- id: required(number)
A system managed unique id for the reaction.
- title: (string)
Name of the reaction
- description: (string)
Description of the reaction.
Example:
Sends an e-mail to the CEO. - type: required(string)
Type of the reaction, currently supported are "email" (send an e-mail) and "hook" (send a web hook message)
- config: (union of alarmLib.EMailTemplate or alarmLib.WebHookTemplate)
An object with the values overriding the values in the template
Examples:
EMailToOtherReceiver:
Sends the email from the template to a different address.{ "address": "ceo@company.com" }OtherMessageToWebhook:
Uses the template for all information, but replaces the content.{ "content": "A different message to the web hook." } - alarm_id: required(number)
A reference to the alarm id
- template_id: (number)
Reference to the template containing the default configuration
- interval: (object)
The definition of sending intervals and repetitions for the reaction. The items are numbers with a time unit (seconds, minutes or hours). If the alarm is deactivated earlier the executions are stopped. If the interval is not defined the reaction will be executed only once right after activation.
- initial: (array of string)
Ordered array of time values for single execution.
- repeat: (string)
Time value for repeating execution.
Examples:
SimpleRepeat:
Repeats the reaction every 5 minutes.{ "repeat": "5m" }IncreasingInterval:
Executes the reaction after 5 seconds, 10 minutes and 1 hour.{ "initial": ["5s", "10m", "1h"] }IntervalAndRepeat:
Executes the reaction after 5 seconds, 10 minutes and repeats afterwards every 30 minutes.{ "initial": ["5s", "10m"], "repeat": "30m" } - initial: (array of string)
Examples:
Email:
An e-mail reaction
{
"id": 437,
"title": "Mail to boss",
"description": "Sends a mail to the boss",
"type": "email",
"config": {
"subject" : "Machine is overheating",
"message" : "The temperature of the machine reaches a critical value.",
"address" : "boss@company.com"
},
"alarm_id": 4,
"interval": {
"initial": ["5m", "15m"],
"repeat": "30m"
}
}
WebHook:
A web hook reaction
{
"id": 443,
"title": "Message to the messenger",
"description": "Sends a message to the messenger",
"type": "hook",
"config": {
"url": "http://messenger/error",
"http_method": "POST",
"content": "The machine temperature is too high",
"header": {
"authorization": "BEARER ey45af=",
"content_type": "plain/text",
"user_agent": "john_doe"
}
},
"alarm_id": 4,
"interval": {
"repeat": "10m"
}
}
HTTP status code 404
If the alarm alarm identified via the property and alarm level was not found
Gets the rection of the alarm identified via the property and alarm level
Updates the reaction of the alarm identified via the property and alarm level
Removes the reaction from the alarm identified via the property and alarm level
get /alarms/config/things/{thing}/properties/{property}/{level}/reactions/{reactionid}
Gets the rection of the alarm identified via the property and alarm level
URI Parameters
- thing: required(string)
Name or Id of the thing
Examples:
Name:
Name of the thingMillingMachine1Id:
Id of the thing42 - property: required(string)
Name of the property, must be unique inside the thing
Example:
temperature - level: required(string)
An user defined level of the alarm. The level is domain specific and part of the unique triplet (thing id, property name and level).
- reactionid: required(number)
A system managed unique id for the reaction.
HTTP status code 200
OK
Body
Media type: application/json
Type: object
Properties- id: required(number)
A system managed unique id for the reaction.
- title: (string)
Name of the reaction
- description: (string)
Description of the reaction.
Example:
Sends an e-mail to the CEO. - type: required(string)
Type of the reaction, currently supported are "email" (send an e-mail) and "hook" (send a web hook message)
- config: (union of alarmLib.EMailTemplate or alarmLib.WebHookTemplate)
An object with the values overriding the values in the template
Examples:
EMailToOtherReceiver:
Sends the email from the template to a different address.{ "address": "ceo@company.com" }OtherMessageToWebhook:
Uses the template for all information, but replaces the content.{ "content": "A different message to the web hook." } - alarm_id: required(number)
A reference to the alarm id
- template_id: (number)
Reference to the template containing the default configuration
- interval: (object)
The definition of sending intervals and repetitions for the reaction. The items are numbers with a time unit (seconds, minutes or hours). If the alarm is deactivated earlier the executions are stopped. If the interval is not defined the reaction will be executed only once right after activation.
- initial: (array of string)
Ordered array of time values for single execution.
- repeat: (string)
Time value for repeating execution.
Examples:
SimpleRepeat:
Repeats the reaction every 5 minutes.{ "repeat": "5m" }IncreasingInterval:
Executes the reaction after 5 seconds, 10 minutes and 1 hour.{ "initial": ["5s", "10m", "1h"] }IntervalAndRepeat:
Executes the reaction after 5 seconds, 10 minutes and repeats afterwards every 30 minutes.{ "initial": ["5s", "10m"], "repeat": "30m" } - initial: (array of string)
Examples:
Email:
An e-mail reaction
{
"id": 437,
"title": "Mail to boss",
"description": "Sends a mail to the boss",
"type": "email",
"config": {
"subject" : "Machine is overheating",
"message" : "The temperature of the machine reaches a critical value.",
"address" : "boss@company.com"
},
"alarm_id": 4,
"interval": {
"initial": ["5m", "15m"],
"repeat": "30m"
}
}
WebHook:
A web hook reaction
{
"id": 443,
"title": "Message to the messenger",
"description": "Sends a message to the messenger",
"type": "hook",
"config": {
"url": "http://messenger/error",
"http_method": "POST",
"content": "The machine temperature is too high",
"header": {
"authorization": "BEARER ey45af=",
"content_type": "plain/text",
"user_agent": "john_doe"
}
},
"alarm_id": 4,
"interval": {
"repeat": "10m"
}
}
HTTP status code 404
If the alarm alarm identified via the property and alarm level was not found
patch /alarms/config/things/{thing}/properties/{property}/{level}/reactions/{reactionid}
Updates the reaction of the alarm identified via the property and alarm level
URI Parameters
- thing: required(string)
Name or Id of the thing
Examples:
Name:
Name of the thingMillingMachine1Id:
Id of the thing42 - property: required(string)
Name of the property, must be unique inside the thing
Example:
temperature - level: required(string)
An user defined level of the alarm. The level is domain specific and part of the unique triplet (thing id, property name and level).
- reactionid: required(number)
A system managed unique id for the reaction.
Body
Media type: application/json
Type: object
Properties- title: (string)
Name of the reaction
- description: (string)
Description of the reaction.
Example:
Sends an e-mail to the CEO. - type: required(string)
Type of the reaction, currently supported are "email" (send an e-mail) and "hook" (send a web hook message)
- config: (union of alarmLib.EMailTemplate or alarmLib.WebHookTemplate)
An object with the values overriding the values in the template
Examples:
EMailToOtherReceiver:
Sends the email from the template to a different address.{ "address": "ceo@company.com" }OtherMessageToWebhook:
Uses the template for all information, but replaces the content.{ "content": "A different message to the web hook." } - alarm_id: required(number)
A reference to the alarm id
- template_id: (number)
Reference to the template containing the default configuration
- interval: (object)
The definition of sending intervals and repetitions for the reaction. The items are numbers with a time unit (seconds, minutes or hours). If the alarm is deactivated earlier the executions are stopped. If the interval is not defined the reaction will be executed only once right after activation.
- initial: (array of string)
Ordered array of time values for single execution.
- repeat: (string)
Time value for repeating execution.
Examples:
SimpleRepeat:
Repeats the reaction every 5 minutes.{ "repeat": "5m" }IncreasingInterval:
Executes the reaction after 5 seconds, 10 minutes and 1 hour.{ "initial": ["5s", "10m", "1h"] }IntervalAndRepeat:
Executes the reaction after 5 seconds, 10 minutes and repeats afterwards every 30 minutes.{ "initial": ["5s", "10m"], "repeat": "30m" } - initial: (array of string)
Examples:
Email:
An e-mail reaction
{
"title": "Mail to boss",
"description": "Sends a mail to the boss",
"type": "email",
"config": {
"address": "john_doe@company.com"
},
"alarm_id": 4,
"template_id": 2,
"interval": {
"initial": ["5m", "15m"],
"repeat": "30m"
}
}
WebHook:
A web hook reaction
{
"title": "Message to the messenger",
"description": "Sends a message to the messenger",
"type": "hook",
"config": {
"content": "The machine temperature is too high"
},
"alarm_id": 4,
"template_id": 1,
"interval": {
"repeat": "10m"
}
}
HTTP status code 200
OK
Body
Media type: application/json
Type: object
Properties- id: required(number)
A system managed unique id for the reaction.
- title: (string)
Name of the reaction
- description: (string)
Description of the reaction.
Example:
Sends an e-mail to the CEO. - type: required(string)
Type of the reaction, currently supported are "email" (send an e-mail) and "hook" (send a web hook message)
- config: (union of alarmLib.EMailTemplate or alarmLib.WebHookTemplate)
An object with the values overriding the values in the template
Examples:
EMailToOtherReceiver:
Sends the email from the template to a different address.{ "address": "ceo@company.com" }OtherMessageToWebhook:
Uses the template for all information, but replaces the content.{ "content": "A different message to the web hook." } - alarm_id: required(number)
A reference to the alarm id
- template_id: (number)
Reference to the template containing the default configuration
- interval: (object)
The definition of sending intervals and repetitions for the reaction. The items are numbers with a time unit (seconds, minutes or hours). If the alarm is deactivated earlier the executions are stopped. If the interval is not defined the reaction will be executed only once right after activation.
- initial: (array of string)
Ordered array of time values for single execution.
- repeat: (string)
Time value for repeating execution.
Examples:
SimpleRepeat:
Repeats the reaction every 5 minutes.{ "repeat": "5m" }IncreasingInterval:
Executes the reaction after 5 seconds, 10 minutes and 1 hour.{ "initial": ["5s", "10m", "1h"] }IntervalAndRepeat:
Executes the reaction after 5 seconds, 10 minutes and repeats afterwards every 30 minutes.{ "initial": ["5s", "10m"], "repeat": "30m" } - initial: (array of string)
Examples:
Email:
An e-mail reaction
{
"id": 437,
"title": "Mail to boss",
"description": "Sends a mail to the boss",
"type": "email",
"config": {
"subject" : "Machine is overheating",
"message" : "The temperature of the machine reaches a critical value.",
"address" : "boss@company.com"
},
"alarm_id": 4,
"interval": {
"initial": ["5m", "15m"],
"repeat": "30m"
}
}
WebHook:
A web hook reaction
{
"id": 443,
"title": "Message to the messenger",
"description": "Sends a message to the messenger",
"type": "hook",
"config": {
"url": "http://messenger/error",
"http_method": "POST",
"content": "The machine temperature is too high",
"header": {
"authorization": "BEARER ey45af=",
"content_type": "plain/text",
"user_agent": "john_doe"
}
},
"alarm_id": 4,
"interval": {
"repeat": "10m"
}
}
HTTP status code 404
If the alarm alarm identified via the property and alarm level was not found
delete /alarms/config/things/{thing}/properties/{property}/{level}/reactions/{reactionid}
Removes the reaction from the alarm identified via the property and alarm level
URI Parameters
- thing: required(string)
Name or Id of the thing
Examples:
Name:
Name of the thingMillingMachine1Id:
Id of the thing42 - property: required(string)
Name of the property, must be unique inside the thing
Example:
temperature - level: required(string)
An user defined level of the alarm. The level is domain specific and part of the unique triplet (thing id, property name and level).
- reactionid: required(number)
A system managed unique id for the reaction.
Alarm History
Create, observe, control and acknowledge alarms, manage reactions to alarms.
Gets the history of all alarms
get /alarms/history
Gets the history of all alarms
HTTP status code 200
OK
Body
Media type: application/json
Type: array of alarmLib.AlarmHistory
Items: AlarmHistory
- alarm_id: required(number)
Unique id of the alarm
- operation: required(string)
Change of the alarm state, one of the values "activated", "deactivated", "enabled", "disabled" or "acknowledged"
- time: required(number)
Unix time in milliseconds of the transition time
- value: (union of string or number or boolean or nil)
Value of the property triggered "activated" or "deactivated" state
- user_id: (number)
User identifier if the alarm was enabled/disabled or acknowledged.
Example:
[
{
"alarm_id": 4,
"operation": "acknowledged",
"time": 1601536521320,
"user_id": 3
},
{
"alarm_id": 4,
"operation": "activated",
"time": 1601532215681,
"value": 75
}
]
Gets the history of all alarms associated with properties of the given thing
get /alarms/history/things/{thing}
Gets the history of all alarms associated with properties of the given thing
URI Parameters
- thing: required(string)
Name or Id of the thing
Examples:
Name:
Name of the thingMillingMachine1Id:
Id of the thing42
HTTP status code 200
OK
Body
Media type: application/json
Type: array of alarmLib.AlarmHistory
Items: AlarmHistory
- alarm_id: required(number)
Unique id of the alarm
- operation: required(string)
Change of the alarm state, one of the values "activated", "deactivated", "enabled", "disabled" or "acknowledged"
- time: required(number)
Unix time in milliseconds of the transition time
- value: (union of string or number or boolean or nil)
Value of the property triggered "activated" or "deactivated" state
- user_id: (number)
User identifier if the alarm was enabled/disabled or acknowledged.
Example:
[
{
"alarm_id": 4,
"operation": "acknowledged",
"time": 1601536521320,
"user_id": 3
},
{
"alarm_id": 4,
"operation": "activated",
"time": 1601532215681,
"value": 75
}
]
HTTP status code 404
If the thing with the given id or name was not found
Gets the history of all alarms associated with the property of the given thing
get /alarms/history/things/{thing}/properties/{property}
Gets the history of all alarms associated with the property of the given thing
URI Parameters
- thing: required(string)
Name or Id of the thing
Examples:
Name:
Name of the thingMillingMachine1Id:
Id of the thing42 - property: required(string)
Name of the property, must be unique inside the thing
Example:
temperature
HTTP status code 200
OK
Body
Media type: application/json
Type: array of alarmLib.AlarmHistory
Items: AlarmHistory
- alarm_id: required(number)
Unique id of the alarm
- operation: required(string)
Change of the alarm state, one of the values "activated", "deactivated", "enabled", "disabled" or "acknowledged"
- time: required(number)
Unix time in milliseconds of the transition time
- value: (union of string or number or boolean or nil)
Value of the property triggered "activated" or "deactivated" state
- user_id: (number)
User identifier if the alarm was enabled/disabled or acknowledged.
Example:
[
{
"alarm_id": 4,
"operation": "acknowledged",
"time": 1601536521320,
"user_id": 3
},
{
"alarm_id": 4,
"operation": "activated",
"time": 1601532215681,
"value": 75
}
]
HTTP status code 404
If the property or the thing with the given id or name was not found
Gets the history of the alarm identified by the property and level
get /alarms/history/things/{thing}/properties/{property}/{level}
Gets the history of the alarm identified by the property and level
URI Parameters
- thing: required(string)
Name or Id of the thing
Examples:
Name:
Name of the thingMillingMachine1Id:
Id of the thing42 - property: required(string)
Name of the property, must be unique inside the thing
Example:
temperature - level: required(string)
An user defined level of the alarm. The level is domain specific and part of the unique triplet (thing id, property name and level).
HTTP status code 200
OK
Body
Media type: application/json
Type: array of alarmLib.AlarmHistory
Items: AlarmHistory
- alarm_id: required(number)
Unique id of the alarm
- operation: required(string)
Change of the alarm state, one of the values "activated", "deactivated", "enabled", "disabled" or "acknowledged"
- time: required(number)
Unix time in milliseconds of the transition time
- value: (union of string or number or boolean or nil)
Value of the property triggered "activated" or "deactivated" state
- user_id: (number)
User identifier if the alarm was enabled/disabled or acknowledged.
Example:
[
{
"alarm_id": 4,
"operation": "acknowledged",
"time": 1601536521320,
"user_id": 3
},
{
"alarm_id": 4,
"operation": "activated",
"time": 1601532215681,
"value": 75
}
]
HTTP status code 404
If the alarm identified by the property and level was not found
Acknowledges the alarm given by the property and the level
post /alarms/history/things/{thing}/properties/{property}/{level}/acknowledge
Acknowledges the alarm given by the property and the level
URI Parameters
- thing: required(string)
Name or Id of the thing
Examples:
Name:
Name of the thingMillingMachine1Id:
Id of the thing42 - property: required(string)
Name of the property, must be unique inside the thing
Example:
temperature - level: required(string)
An user defined level of the alarm. The level is domain specific and part of the unique triplet (thing id, property name and level).
Body
Media type: application/json
Type: any
Example:
{}Live Alarm View
Create, observe, control and acknowledge alarms, manage reactions to alarms.
Gets the current state of all alarms
get /alarms/live
Gets the current state of all alarms
HTTP status code 200
OK
Body
Media type: application/json
Type: array of alarmLib.AlarmStatus
Items: AlarmStatus
- id: required(number)
Unique id of the alarm
- level: required(string)
An user defined level of the alarm. The level is domain specific and part of the unique triplet (thing id, property name and level).
- property: required(string)
Name of the property, must be unique inside the thing
Example:
temperature - thing: required(number)
Unique id of the thing
- severity: required(string)
One of the values "info", "warning", "error" and "critical". Classifies the alarm in a common way regarding its impact.
- title: required(string)
A meaningful title of the alarm
- enabled: required(boolean)
If true the alarm is enabled and reacts on value changes of the observed property, if set to false the alarm will be not activated.
- activated: required(boolean)
If true the property value reached the trigger range and the observation time is over.
- acknowledged: required(boolean)
If true, the alarm was acknowledged by an user.
Example:
[
{
"id": 4,
"level": "high",
"property": "temperature",
"thing": 4827858800541171713,
"severity": "warning",
"title": "Machine overheating",
"enabled": true,
"activated": false,
"acknowledged": false
},
{
"id": 5,
"level": "low",
"property": "temperature",
"thing": 4827858800541171713,
"severity": "warning",
"title": "Machine to cold",
"enabled": true,
"activated": true,
"acknowledged": true
}
]
Gets the current state of all alarms associated with properties of the given thing
get /alarms/live/things/{thing}
Gets the current state of all alarms associated with properties of the given thing
URI Parameters
- thing: required(string)
Name or Id of the thing
Examples:
Name:
Name of the thingMillingMachine1Id:
Id of the thing42
HTTP status code 200
OK
Body
Media type: application/json
Type: array of alarmLib.AlarmStatus
Items: AlarmStatus
- id: required(number)
Unique id of the alarm
- level: required(string)
An user defined level of the alarm. The level is domain specific and part of the unique triplet (thing id, property name and level).
- property: required(string)
Name of the property, must be unique inside the thing
Example:
temperature - thing: required(number)
Unique id of the thing
- severity: required(string)
One of the values "info", "warning", "error" and "critical". Classifies the alarm in a common way regarding its impact.
- title: required(string)
A meaningful title of the alarm
- enabled: required(boolean)
If true the alarm is enabled and reacts on value changes of the observed property, if set to false the alarm will be not activated.
- activated: required(boolean)
If true the property value reached the trigger range and the observation time is over.
- acknowledged: required(boolean)
If true, the alarm was acknowledged by an user.
Example:
[
{
"id": 4,
"level": "high",
"property": "temperature",
"thing": 4827858800541171713,
"severity": "warning",
"title": "Machine overheating",
"enabled": true,
"activated": false,
"acknowledged": false
},
{
"id": 5,
"level": "low",
"property": "temperature",
"thing": 4827858800541171713,
"severity": "warning",
"title": "Machine to cold",
"enabled": true,
"activated": true,
"acknowledged": true
}
]
HTTP status code 404
If the thing with the given id or name was not found
Gets the current state of all alarms associated with the property of the given thing
get /alarms/live/things/{thing}/properties/{property}
Gets the current state of all alarms associated with the property of the given thing
URI Parameters
- thing: required(string)
Name or Id of the thing
Examples:
Name:
Name of the thingMillingMachine1Id:
Id of the thing42 - property: required(string)
Name of the property, must be unique inside the thing
Example:
temperature
HTTP status code 200
OK
Body
Media type: application/json
Type: array of alarmLib.AlarmStatus
Items: AlarmStatus
- id: required(number)
Unique id of the alarm
- level: required(string)
An user defined level of the alarm. The level is domain specific and part of the unique triplet (thing id, property name and level).
- property: required(string)
Name of the property, must be unique inside the thing
Example:
temperature - thing: required(number)
Unique id of the thing
- severity: required(string)
One of the values "info", "warning", "error" and "critical". Classifies the alarm in a common way regarding its impact.
- title: required(string)
A meaningful title of the alarm
- enabled: required(boolean)
If true the alarm is enabled and reacts on value changes of the observed property, if set to false the alarm will be not activated.
- activated: required(boolean)
If true the property value reached the trigger range and the observation time is over.
- acknowledged: required(boolean)
If true, the alarm was acknowledged by an user.
Example:
[
{
"id": 4,
"level": "high",
"property": "temperature",
"thing": 4827858800541171713,
"severity": "warning",
"title": "Machine overheating",
"enabled": true,
"activated": false,
"acknowledged": false
},
{
"id": 5,
"level": "low",
"property": "temperature",
"thing": 4827858800541171713,
"severity": "warning",
"title": "Machine to cold",
"enabled": true,
"activated": true,
"acknowledged": true
}
]
HTTP status code 404
If the property or the thing with the given id or name was not found
Gets the current state of the alarm identified by the property and level
get /alarms/live/things/{thing}/properties/{property}/{level}
Gets the current state of the alarm identified by the property and level
URI Parameters
- thing: required(string)
Name or Id of the thing
Examples:
Name:
Name of the thingMillingMachine1Id:
Id of the thing42 - property: required(string)
Name of the property, must be unique inside the thing
Example:
temperature - level: required(string)
An user defined level of the alarm. The level is domain specific and part of the unique triplet (thing id, property name and level).
HTTP status code 200
OK
Body
Media type: application/json
Type: object
Properties- id: required(number)
Unique id of the alarm
- level: required(string)
An user defined level of the alarm. The level is domain specific and part of the unique triplet (thing id, property name and level).
- property: required(string)
Name of the property, must be unique inside the thing
Example:
temperature - thing: required(number)
Unique id of the thing
- severity: required(string)
One of the values "info", "warning", "error" and "critical". Classifies the alarm in a common way regarding its impact.
- title: required(string)
A meaningful title of the alarm
- enabled: required(boolean)
If true the alarm is enabled and reacts on value changes of the observed property, if set to false the alarm will be not activated.
- activated: required(boolean)
If true the property value reached the trigger range and the observation time is over.
- acknowledged: required(boolean)
If true, the alarm was acknowledged by an user.
Example:
{
"id": 4,
"level": "high",
"property": "temperature",
"thing": 4827858800541171713,
"severity": "warning",
"title": "Machine overheating",
"enabled": true,
"activated": false,
"acknowledged": false
}
HTTP status code 404
If the alarm identified by the property and level was not found
Acknowledges the alarm given by the property and the level
post /alarms/live/things/{thing}/properties/{property}/{level}/acknowledge
Acknowledges the alarm given by the property and the level
URI Parameters
- thing: required(string)
Name or Id of the thing
Examples:
Name:
Name of the thingMillingMachine1Id:
Id of the thing42 - property: required(string)
Name of the property, must be unique inside the thing
Example:
temperature - level: required(string)
An user defined level of the alarm. The level is domain specific and part of the unique triplet (thing id, property name and level).
Body
Media type: application/json
Type: any
Example:
{}Alarm Reaction Templates
Create, observe, control and acknowledge alarms, manage reactions to alarms.
Gets the full template list
Adds a template to the IoTHub
get /alarms/templates
Gets the full template list
HTTP status code 200
OK
Body
Media type: application/json
Type: array of alarmLib.ReactionTemplate
Items: ReactionTemplate
- id: required(number)
A system managed unique identifier of the template, used to link an alarm reaction with the template using its default configuration fields. If the id is 0, no template is used.
- title: required(string)
A human readable name for the template, must not be unique, but should.
- description: required(string)
Meaningful description of the template helping the search for the rigth template of an alarm reaction
- type: required(string)
Type of the reaction, currently supported are "email" (send an e-mail) and "hook" (send a web hook message)
- config: required(union of alarmLib.EMailTemplate or alarmLib.WebHookTemplate)
Depending on the type a set of configuration items must be given as default for the alarm reaction.
Example:
[
{
"id": 2,
"title": "MachineOverheatingEmailTemplate",
"description": "Template for sending an e-mail if a machine overheats.",
"type": "email",
"config": {
"subject" : "Machine is overheating",
"message" : "The temperature of the machine reaches a critical value.",
"address" : "boss@company.com"
}
},
{
"id": 4,
"title": "MachineOverheatingMessengerTemplate",
"description": "Template for sending a message to the messenger if a machine overheats.",
"type": "hook",
"config": {
"url": "http://messanger/error",
"http_method": "POST",
"content": "Machine is to hot.",
"header": {
"authorization": "BEARER ey45af=",
"content_type": "plain/text",
"user_agent": "john_doe"
}
}
}
]
post /alarms/templates
Adds a template to the IoTHub
Body
Media type: application/json
Type: object
Properties- id: required(number)
A system managed unique identifier of the template, used to link an alarm reaction with the template using its default configuration fields. If the id is 0, no template is used.
- title: required(string)
A human readable name for the template, must not be unique, but should.
- description: required(string)
Meaningful description of the template helping the search for the rigth template of an alarm reaction
- type: required(string)
Type of the reaction, currently supported are "email" (send an e-mail) and "hook" (send a web hook message)
- config: required(union of alarmLib.EMailTemplate or alarmLib.WebHookTemplate)
Depending on the type a set of configuration items must be given as default for the alarm reaction.
Examples:
EMailTemplate:
A template for sending an email as reaction of an alarm
{
"id": 2,
"title": "MachineOverheatingEmailTemplate",
"description": "Template for sending an e-mail if a machine overheats.",
"type": "email",
"config": {
"subject" : "Machine is overheating",
"message" : "The temperature of the machine reaches a critical value.",
"address" : "boss@company.com"
}
}
WebhookTemplate:
A template for sending a content to a web hook
{
"id": 4,
"title": "MachineOverheatingMessengerTemplate",
"description": "Template for sending a message to the messenger if a machine overheats.",
"type": "hook",
"config": {
"url": "http://messanger/error",
"http_method": "POST",
"content": "Machine is to hot.",
"header": {
"authorization": "BEARER ey45af=",
"content_type": "plain/text",
"user_agent": "john_doe"
}
}
}
HTTP status code 201
Created
Gets the given reaction template
Updates the reaction template
Removes the reaction template
get /alarms/templates/{templateid}
Gets the given reaction template
URI Parameters
- templateid: required(number)
A system managed unique identifier of the template, used to link an alarm reaction with the template using its default configuration fields. If the id is 0, no template is used.
HTTP status code 200
OK
Body
Media type: application/json
Type: object
Properties- id: required(number)
A system managed unique identifier of the template, used to link an alarm reaction with the template using its default configuration fields. If the id is 0, no template is used.
- title: required(string)
A human readable name for the template, must not be unique, but should.
- description: required(string)
Meaningful description of the template helping the search for the rigth template of an alarm reaction
- type: required(string)
Type of the reaction, currently supported are "email" (send an e-mail) and "hook" (send a web hook message)
- config: required(union of alarmLib.EMailTemplate or alarmLib.WebHookTemplate)
Depending on the type a set of configuration items must be given as default for the alarm reaction.
Examples:
EMailTemplate:
A template for sending an email as reaction of an alarm
{
"id": 2,
"title": "MachineOverheatingEmailTemplate",
"description": "Template for sending an e-mail if a machine overheats.",
"type": "email",
"config": {
"subject" : "Machine is overheating",
"message" : "The temperature of the machine reaches a critical value.",
"address" : "boss@company.com"
}
}
WebhookTemplate:
A template for sending a content to a web hook
{
"id": 4,
"title": "MachineOverheatingMessengerTemplate",
"description": "Template for sending a message to the messenger if a machine overheats.",
"type": "hook",
"config": {
"url": "http://messanger/error",
"http_method": "POST",
"content": "Machine is to hot.",
"header": {
"authorization": "BEARER ey45af=",
"content_type": "plain/text",
"user_agent": "john_doe"
}
}
}
HTTP status code 404
If the template with the given id was not found
patch /alarms/templates/{templateid}
Updates the reaction template
URI Parameters
- templateid: required(number)
A system managed unique identifier of the template, used to link an alarm reaction with the template using its default configuration fields. If the id is 0, no template is used.
Body
Media type: application/json
Type: object
Properties- title: (string)
A human readable name for the template, must not be unique, but should.
- description: (string)
Meaningful description of the template helping the search for the rigth template of an alarm reaction
- type: (string)
Type of the reaction, currently supported are "email" (send an e-mail) and "hook" (send a web hook message)
- config: (union of alarmLib.EMailTemplate or alarmLib.WebHookTemplate)
Depending on the type a set of configuration items must be given as default for the alarm reaction.
Examples:
EMailTemplate:
Changes an existing e-mail template
{
"description": "Template for sending an e-mail only to the CEO if a machine overheats.",
"config": {
"address" : "ceo@company.com"
}
}
WebhookTemplate:
Changes an existing web hook template
{
"config": {
"url": "http://messanger/urgent"
}
}
HTTP status code 200
OK
Body
Media type: application/json
Type: object
Properties- id: required(number)
A system managed unique identifier of the template, used to link an alarm reaction with the template using its default configuration fields. If the id is 0, no template is used.
- title: required(string)
A human readable name for the template, must not be unique, but should.
- description: required(string)
Meaningful description of the template helping the search for the rigth template of an alarm reaction
- type: required(string)
Type of the reaction, currently supported are "email" (send an e-mail) and "hook" (send a web hook message)
- config: required(union of alarmLib.EMailTemplate or alarmLib.WebHookTemplate)
Depending on the type a set of configuration items must be given as default for the alarm reaction.
Examples:
EMailTemplate:
A template for sending an email as reaction of an alarm
{
"id": 2,
"title": "MachineOverheatingEmailTemplate",
"description": "Template for sending an e-mail if a machine overheats.",
"type": "email",
"config": {
"subject" : "Machine is overheating",
"message" : "The temperature of the machine reaches a critical value.",
"address" : "boss@company.com"
}
}
WebhookTemplate:
A template for sending a content to a web hook
{
"id": 4,
"title": "MachineOverheatingMessengerTemplate",
"description": "Template for sending a message to the messenger if a machine overheats.",
"type": "hook",
"config": {
"url": "http://messanger/error",
"http_method": "POST",
"content": "Machine is to hot.",
"header": {
"authorization": "BEARER ey45af=",
"content_type": "plain/text",
"user_agent": "john_doe"
}
}
}
HTTP status code 404
If the template with the given id was not found
delete /alarms/templates/{templateid}
Removes the reaction template
URI Parameters
- templateid: required(number)
A system managed unique identifier of the template, used to link an alarm reaction with the template using its default configuration fields. If the id is 0, no template is used.