Skip to main content

Notification2

The examples on this pages require you to have the Notifications 2.0 enabled on your tenant. Refer to the official documentation for details about the requirements.

The Notifications 2.0 API allows applications or microservices to receive and process notifications generated by the use of the Cumulocity IoT REST or MQTT APIs (device management, measurements, alarms, events and other platform APIs) in a reliable manner.

caution

Carefully consider what you want to subscribe to before creating the subscription. Try to make the smallest possible cross section of notifications. Avoid subscribing to all notifications if you can, or make sure your subscriber can consume the notifications quicker than the notifications are created (over an extended time period).

Example: Subscribe using a single consumer​

This example will show you how to create a subscription for a single device and subscribe to it's alarms, events, operations and managed object updates.

  1. Create a new device which we will be using in the example

    c8y agents create --name sub_test001
    Output
    | id              | name             |
    |-----------------|------------------|
    | 1427421025      | sub_test001      |

  2. Create a subscription defining which types of updates we will be interested in. This does not start listening to the subscription, it only defines the subscription.

    c8y notification2 subscriptions create \
        --name mydevice \
        --device sub_test001 \
        --context mo \
        --apiFilter "events" --apiFilter "alarms" --apiFilter "operations" --apiFilter "managedobjects"
    Output
    | id            | subscription  | context    | source.id       | source.name      | subscriptionFilter.apis.0 |
    |---------------|---------------|------------|-----------------|------------------|---------------------------|
    | 27598780      | mydevice      | mo         | 1427421025      | sub_test001      | *                         |
    caution

    If you use the --apiFilter "*" option, then you may get two updates per alarm and event updates. This is because the wildcard apiFilter (*) includes both alarms and alarmsWithChildren as well as events and eventsWithChildren. If you don't want duplicated updates, then don't use the wildcard apiFilter (*) and use the individual apiFilters instead.

  3. Start consuming the notifications (the command will create a new token automatically)

    c8y notification2 subscriptions subscribe --name mydevice --raw -c
    note

    Here the subscribe command will automatically create a token to use for the subscription. If you would like to re-use an existing token that you may have, you can pass the token via the --token flag.

    The renewal of the token will be handled automatically by the client.

  4. Test the subscription by creating a new terminal and test some test data.

    Open a new terminal, and set the go-c8y-cli session, then run the following command to generate the data.

    c8y alarms create --device sub_test001 --text "Example alarm" --type "c8y_Example" --severity MAJOR
    c8y events create --device sub_test001 --text "Example event" --type "c8y_Example"
    c8y operations create --device sub_test001 --template "{c8y_Command:{text:'ls -l'}}" --description "Execute command"
    c8y devices update --id sub_test001 --template "{example_SomeUpdate:{time: _.Now()}}"
    Output (from subscription)
    {"count":3,"creationTime":"2023-06-08T18:06:08.339Z","firstOccurrenceTime":"2023-06-08T20:06:08.263+02:00","history":{"auditRecords":[],"self":"https://t12345.example.cumulocity.com/audit/auditRecords"},"id":"27496867","lastUpdated":"2023-06-08T18:34:50.244Z","self":"https://t12345.example.cumulocity.com/alarm/alarms/27496867","severity":"MAJOR","source":{"id":"1427421025","self":"https://t12345.example.cumulocity.com/inventory/managedObjects/1427421025"},"status":"ACTIVE","text":"Example event","time":"2023-06-08T20:34:49.154+02:00","type":"c8y_Example"}
    {"creationTime":"2023-06-08T18:34:55.363Z","id":"27496873","lastUpdated":"2023-06-08T18:34:55.363Z","self":"https://t12345.example.cumulocity.com/event/events/27496873","source":{"id":"1427421025","name":"sub_test001","self":"https://t12345.example.cumulocity.com/inventory/managedObjects/1427421025"},"text":"Example event","time":"2023-06-08T20:34:54.899+02:00","type":"c8y_Example"}
    {"c8y_Command":{"text":"ls -l"},"creationTime":"2023-06-08T18:34:59.825Z","description":"Execute command","deviceId":"1427421025","deviceName":"sub_test001","id":"27598786","self":"https://t12345.example.cumulocity.com/devicecontrol/operations/27598786","status":"PENDING"}
    {"additionParents":{"references":[],"self":"https://t12345.example.cumulocity.com/inventory/managedObjects/1427421025/additionParents"},"assetParents":{"references":[],"self":"https://t12345.example.cumulocity.com/inventory/managedObjects/1427421025/assetParents"},"c8y_ActiveAlarmsStatus":{"major":1},"c8y_IsDevice":{},"childAdditions":{"references":[],"self":"https://t12345.example.cumulocity.com/inventory/managedObjects/1427421025/childAdditions"},"childAssets":{"references":[],"self":"https://t12345.example.cumulocity.com/inventory/managedObjects/1427421025/childAssets"},"childDevices":{"references":[],"self":"https://t12345.example.cumulocity.com/inventory/managedObjects/1427421025/childDevices"},"com_cumulocity_model_Agent":{},"creationTime":"2023-06-08T17:52:54.050Z","deviceParents":{"references":[],"self":"https://t12345.example.cumulocity.com/inventory/managedObjects/1427421025/deviceParents"},"example_SomeUpdate":{"time":"2023-06-08T20:35:04.115+02:00"},"id":"1427421025","lastUpdated":"2023-06-08T18:35:04.559Z","name":"sub_test001","owner":"peterpi","self":"https://t12345.example.cumulocity.com/inventory/managedObjects/1427421025"}

  5. Delete the subscription after you are finished (to prevent consuming unnecessary platform resources)

    c8y notification2 subscriptions deleteBySource --context mo --device sub_test001

Example: Subscribe to operations from multiple devices using a shared token​

This example shows how to subscribe to operations for a group of devices. It uses a single shared token across multiple consumers. Together the consumers work as one logical processing unit with the workload balanced across each of the consumers (balanced by the platform). More details about shared tokens can be found on the official Cumulocity IoT documentation.

  1. First create some dummy devices which will be used in the following commands

    c8y util repeat 5 \
    | c8y template execute --template "'device_%02d' % input.index" \
    | c8y agents create --dry
    Output
    | id              | name               | type          | owner          | lastUpdated                   | c8y_availability.status |
    |-----------------|--------------------|---------------|----------------|-------------------------------|-------------------------|
    | 1027421019      | device_01          |               | peterpi        | 2023-06-08T15:57:19.985Z      |                         |
    | 8327496861      | device_02          |               | peterpi        | 2023-06-08T15:57:20.193Z      |                         |
    | 2527421020      | device_03          |               | peterpi        | 2023-06-08T15:57:20.320Z      |                         |
    | 3427655692      | device_04          |               | peterpi        | 2023-06-08T15:57:20.474Z      |                         |
    | 9427421021      | device_05          |               | peterpi        | 2023-06-08T15:57:20.585Z      |                         |

  1. Create multiple subscriptions using the same subscription name

    Here we're using the devices created from the previous step. The key is to use the same subscription name as it allows the subscriber to receive operations from a specific group of devices.

    c8y devices list --name "device*" \
    | c8y notification2 subscriptions create --apiFilter operations --name devicegroup --context mo
    Output
    | id            | subscription     | context    | source.id       | source.name          | subscriptionFilter.apis.0 |
    |---------------|------------------|------------|-----------------|----------------------|---------------------------|
    | 27421022      | devicegroup      | mo         | 8327496861      |                      | operations                |
    | 27474610      | devicegroup      | mo         | 2527421020      |                      | operations                |
    | 27474612      | devicegroup      | mo         | 3427655692      |                      | operations                |
    | 27598708      | devicegroup      | mo         | 9427421021      |                      | operations                |
    | 27655711      | devicegroup      | mo         | 1027421019      |                      | operations                |

  2. Create a shared token and print it out on the console as it is needed in the following steps

    c8y notification2 tokens create --name devicegroup --shared --select token -o csv

  3. Now you will need to create two new terminals where each new terminal will be a new client.

    For each new terminal you will have to run the following steps:

    1. Open the terminal
    2. Set the go-c8y-cli session using set-session
    3. Set a variable to hold the token from the previous step.
    4. Start the subscription, each terminal needs to use a different consumer name

    Below shows an example of this process:

    Open terminal 1 (client 1)

    set-session
    TOKEN="<token>"
    c8y notification2 subscriptions subscribe --token "$TOKEN" --consumer client1

    Open terminal 2 (client 2)

    set-session
    TOKEN="<token>"
    c8y notification2 subscriptions subscribe --token "$TOKEN" --consumer client2
    note

    You will have to activate the c8y session in each new terminal so that go-c8y-cli knows which Cumulocity Host to use.

  4. In the original terminal (whilst the other 2 terminals are still running), test out the subscription by creating some operations (1 for each device):

    c8y devices list --name "device*" \
    | c8y operations create --data "c8y_Command.text=ls -l" --description "Execute command"
    Client 1 output
    | c8y_Command.text | creationTime                  | description          | deviceId        | deviceName         | id        |
    |------------------|-------------------------------|----------------------|-----------------|--------------------|-----------|
    | ls -l            | 2023-06-08T16:19:12.816Z      | Execute command      | 8327496861      | device_02      | 27598772  |
    | ls -l            | 2023-06-08T16:19:12.872Z      | Execute command      | 2527421020      | device_03      | 27598774  |
    | ls -l            | 2023-06-08T16:19:12.973Z      | Execute command      | 9427421021      | device_05      | 27598778  |
    Client 2 output
    | c8y_Command.text | creationTime                  | description          | deviceId        | deviceName         | id       |
    |------------------|-------------------------------|----------------------|-----------------|--------------------|----------|
    | ls -l            | 2023-06-08T16:19:12.744Z      | Execute command      | 1027421019      | device_01      | 27598770 |
    | ls -l            | 2023-06-08T16:19:12.921Z      | Execute command      | 3427655692      | device_04      | 27598776 |
    note

    Since we are using a shared token here, the devices will be allocated to devices (sources) will stick to specific consumers so that a consumer will always receive operations from the same device. See the official documentation for the full details.