Device Notifications

📘

This page is a work in progress

This group of REST API allows analysing notifications sent by a remote device to track asynchronous operations progress (on the same device). Every notification is always related to an Operation, and every Operation may have multiple Notifications related to it.

Get all the Device Registry Notifications

The following API allows one to retrieve all the device registry notifications on the given device:

GET /{scopeId}/devices/{deviceId}/operations/{operationId}/notifications

The required path parameters to be used with this call are:

• {scopeId} is the scopeId of the tenant (account) to which the desired device belongs and can be retrieved from the response of the authentication call; the "_" character can be used for indicating the scopeId of the user currently authenticated with the token;
• {deviceId} is the id of the desired device;
• {operationId} is the id of the registry operation to which the notification refers.

It is also possible to add optional query parameters :

• resource is a string value that represents the resource of the notification in which to search the results;
• offset is an integer value which represents the result set offset;
• limit is an integer value which represents the result set limit.

For instance:

GET /QNvLTfKO1hy/devices/Psx7WSjzxGU/operations/WOBK1_0Nc68/notifications

Response

The response of this call represents the list of the device management registry notifications available on the given device. As an example:

{
  "type": "managementOperationNotificationListResult",
  "limitExceeded": false,
  "size": 2,
  "items": [
    {
      "type": "managementOperationNotification",
      "id": "RGoRWw9Pkhc",
      "scopeId": "AQ",
      "createdOn": "2019-11-15T11:27:25.331Z",
      "createdBy": "Ag",
      "operationId": "cjmXXKvLUY8",
      "progress": 0,
      "resource": "download",
      "sentOn": "2019-11-15T11:27:25.267Z",
      "status": "RUNNING"
    },
    {
      "type": "managementOperationNotification",
      "id": "f1Hu1T8iIRw",
      "scopeId": "AQ",
      "createdOn": "2019-11-15T11:27:32.331Z",
      "createdBy": "Ag",
      "operationId": "cjmXXKvLUY8",
      "progress": 5,
      "resource": "download",
      "sentOn": "2019-11-15T11:27:32.277Z",
      "status": "RUNNING"
    }
  ]
}

Get a single Device Registry Notifications

The following API allows one to retrieve a specific registry notification on the given device:

GET /{scopeId}/devices/{deviceId}/operations/{operationId}/notifications/{notificationId}

The required path parameters to be used with this call are:

• {scopeId} is the scopeId of the tenant (account) to which the desired device belongs and can be retrieved from the response of the authentication call; the "_" character can be used for indicating the scopeId of the user currently authenticated with the token;
• {deviceId} is the id of the desired device;
• {operationId} is the id of the registry operation to which the notification refers;
• {notificationId} is the id of the registry notification.

Response

The response of this call represents the details of the requested registry notification on the given device. As an example:

{
  "type": "managementOperationNotification",
  "id": "RGoRWw9Pkhc",
  "scopeId": "AQ",
  "createdOn": "2019-11-15T11:27:25.331Z",
  "createdBy": "Ag",
  "operationId": "cjmXXKvLUY8",
  "progress": 0,
  "resource": "download",
  "sentOn": "2019-11-15T11:27:25.267Z",
  "status": "RUNNING"
}

Delete a single Registry Notification

The following API allows one to delete a specific registry notification on the given device:

DELETE /{scopeId}/devices/{deviceId}/operations/{operationId}/notifications/{notificationId}

The required path parameters to be used with this call are:

• {scopeId} is the scopeId of the tenant (account) to which the desired device belongs and can be retrieved from the response of the authentication call; the "_" character can be used for indicating the scopeId of the user currently authenticated with the token;
• {deviceId} is the id of the desired device;
• {operationId} is the id of the registry operation to which the notification refers;
• {notificationId} is the id of the registry notification.

Response

The response of this call will consist in an HTTP 200 status code in case the notification has been successfully deleted.

Query the Registry Notifications

The following API allows one to query the registry notifications on the given device:

POST /{scopeId}/devices/{deviceId}/operations/{operationId}/notifications/_query

The required path parameters to be used with this call are:

• {scopeId} is the scopeId of the tenant (account) to which the desired device belongs and can be retrieved from the response of the authentication call; the "_" character can be used for indicating the scopeId of the user currently authenticated with the token;
• {deviceId} is the id of the desired device;
• {operationId} is the id of the registry operation to which the notification refers.

Body

This call have a required body parameter that defines an object to filter the query results. As an example:

{
  "offset": 0,
  "limit": 50
}

Response

The response of this call represents the results of the query on the given device. As an example:

{
  "type": "managementOperationNotificationListResult",
  "limitExceeded": false,
  "size": 2,
  "items": [
    {
      "type": "managementOperationNotification",
      "id": "RGoRWw9Pkhc",
      "scopeId": "AQ",
      "createdOn": "2019-11-15T11:27:25.331Z",
      "createdBy": "Ag",
      "operationId": "cjmXXKvLUY8",
      "progress": 0,
      "resource": "download",
      "sentOn": "2019-11-15T11:27:25.267Z",
      "status": "RUNNING"
    },
    {
      "type": "managementOperationNotification",
      "id": "f1Hu1T8iIRw",
      "scopeId": "AQ",
      "createdOn": "2019-11-15T11:27:32.331Z",
      "createdBy": "Ag",
      "operationId": "cjmXXKvLUY8",
      "progress": 5,
      "resource": "download",
      "sentOn": "2019-11-15T11:27:32.277Z",
      "status": "RUNNING"
    }
  ]
}

Count the Registry Notification

The following API allows one to count the registry notifications on the given device:

POST /{scopeId}/devices/{deviceId}/operations/{operationId}/notifications/_count

The required path parameters to be used with this call are:

• {scopeId} is the scopeId of the tenant (account) to which the desired device belongs and can be retrieved from the response of the authentication call; the "_" character can be used for indicating the scopeId of the user currently authenticated with the token;
• {deviceId} is the id of the desired device;
• {operationId} is the id of the registry operation to which the notification refers.

Body

This call have a required body parameter that defines an object to filter the count result. As an example:

{
  "offset": 0,
  "limit": 50
}

Response

The response of this call represents the number of the matching notifications on the given device. As an example:

{
  "count": 0
}