Working with Messages, Notifications, and Files

Devices can communicate with each other using messages, notifications, and sharing files.

Using messaging

Messaging permits a device (sender) to send a message to another device (target device). Any data within a JSON object is supported. Messages are secure because messages are exchanged over a Secure Socket Layer (SSL) connection and devices (sender and target devices) authenticate with the BlackBerry IoT Platform. Messages can be exchanged between devices to do things such as:

Target devices use GET commands to read the queued messages from the BlackBerry IoT Platform. Messages are exchanged using JSON-formatted objects that are stored in the cloud. Each message includes the following fields:

For details about the fields, see messages in the HTTPS REST API.

Detailed workflow of using messaging

Before a message can be sent, the sender must be granted the message.create.<messagetype>, where <messagetype> aligns to application-defined message type. After the capability has been granted to the sender for the target device, messages can be sent using a POST command. Depending on the requirements of the application, capabilities can be granted using a specific message type.

For example, lets say that a target device handles the message types of hello and bye. The capability message.create.hello must be granted on the sending device if you wanted it to send the message type of hello. However, if you wanted the sender to send all message types, you must grant the capability to send each message type individually. In this case, you must grant capabilities for both message.create.hello and message.create.bye. If you had a third message type, you would need to grant that message type as a capability as well.

If the required capabilities aren't configured for the sender, it receives a Not Authorized response when trying to send a message. It's important to remember that the message types are application-defined and the message types are not managed by the BlackBerry IoT Platform.

Messages are read by the target device when it's ready. Allowing the target device to choose when to read its messages is useful, because it isn't possible for the BlackBerry IoT Platform to know whether a device is active or in a state that's ready to read messages. It's possible that devices aren't always connected to the cloud due to various reasons, such as networking issues, internal state issue, or even by design. This workflow also allows developers to create application logic to read messages when it makes sense, such at predefined times, or when a notification is received. Since all messages are queued and stored on the BlackBerry IoT Platform, a watermark identifier is used to identify where in the queue, the last message was acknowledged by a target device. The watermark identifier establishes where after, the target device can start reading messages. The watermark identifier is a system-generated UUID.

When the target device makes a request to get messages, it can optionally specify to retrieve up to 25 messages at a time. If no number is specified, the default is to read up to 25 messages. Messages should be read by the application in a sequential fashion. As part of processing the messages, an acknowledgment must be sent back to the BlackBerry IoT Platform to indicate that the message was read. Messages can be acknowledged one at a time using the watermark identifier. It's also possible to acknowledge a later message that was received to acknowledge all messages up to and including the acknowledged message. To acknowledge a message, the target device must send the watermark identifier using PUTto the BlackBerry IoT Platform. After a message has been acknowledged, the device can no longer read that message.

For example, let's say a device sends messages 1-7 - message zero was sent previously and acknowledged. As such, the watermark is at message 0. Now, the target device reads four messages, therefore, . messages 1, 2, 3, and 4 are read because they are after the watermark. Then, the target device process the first three messages and send one acknowledgment for the third message using its watermark identifier to acknowledge messages 1, 2, and 3. This acknowledgment moves the watermark to message 3. However, if a network error (or some other fault) occurs while sending the acknowledgment for message 4, that acknowledgment for message 4 wasn't received. As a result, when the target device reads four messages again, it starts reading after the last watermark identifier, which is still at message 3, so messages 4, 5, 6, 7 are read. Yes, message 4 is reread because the acknowledgment for message 4 was never received. The diagram below illustrates how this example:

Messaging example

Conversely, if the target device doesn't send an acknowledgment for any of the first three messages or if the acknowledged message was lost, the target device would reread messages 1, 2, and 3 because the watermark hasn't changed. It's important that target devices send an acknowledgment for messages that are read, otherwise the watermark never moves and the same messages are read again.

Working with notifications

Devices can register to receive notifications. Notifications are useful for letting a device know when:

Notifications are received only when a device is connected to the BlackBerry IoT Platform. Notifications that are sent while the device is offline aren't queued nor resent.

You might want to receive notifications when data has changed on other devices for these reasons:

You might also want to receive notifications as an event-driven mechanism to download a file or to let you know that a file may have changed on another device.

Note: If you are interested in getting information to build historical charts or reports, consider using firehoses instead of using notifications.

Notifications are extremely useful for providing a mechanism to let target devices know when a new message is available on the BlackBerry IoT Platform. Being notified improves the application's performance, rather than using alternatives such as polling or checking for messages at predefined times. It's important to remember that if a device isn't connected, it won't receive notifications. Therefore, the application logic for working with messages should follow the workflow described in Detailed workflow of using messaging.

To register for a notification, you must specify a filter. If you don't specify a filter, a 400 error is returned. You can use different types of filters to get notifications about changes to files, messages, and data. For more information about the type of filters you configure, see Using notification filters.

Payload for a notification response

When you receive a notification, it uses this schema for the payload:

[
  {
    "type": "notification type",
    "action": "action",
    "data": "JSON object"
  }
]
For more information about the schema, see Notification Response Class in the REST API documentation.

Use notification filters

These are the types of filters that you can configure using JSON and the response payload you receive:

For more information about notifications, see notifications in the REST API documentation.

Working with files

Authenticated devices can post (upload) files that other authenticated devices can download. As part of creating and uploading the file contents, additional metadata can be created to describe the file. After a file is uploaded, its contents can't be changed. Therefore, if you want to change the contents of a file, delete it, and then upload the file again.

Devices can always perform all operations on files that that belong to them. A device can perform these operations to the files belonging to another device when granted the necessary capabilities:

For more information working with file operations, see files in the REST API documentation.