|Document Number |TR-0075-Developer_Guide_Advanced_Subscription_and_Notification-V0_0_1 |
|Document Name: |Developer Guide: Advanced Subscription and Notification |
|Date: |2022-03-09 |
|Abstract: |This developer guide describes the oneM2M Subscription resource features and capabilities. It describes some of the additional functionality of the <subscription> resource and some exemplary use cases and examples. |
|Template Version: January 2017 (Do not modify) |Template Version: January 2017 (Do not modify) |
||
The present document is provided for future development work within oneM2M only. The Partners accept no liability for any use of this report.
The present document has not been subject to any approval process by the oneM2M Partners Type 1. Published oneM2M specifications and reports for implementation should be obtained via the oneM2M Partners' Publications Offices.
<br/>About oneM2M
The purpose and goal of oneM2M is to develop technical specifications which address the need for a common M2M Service Layer that can be readily embedded within various hardware and software, and relied upon to connect the myriad of devices in the field with M2M application servers worldwide.
More information about oneM2M may be found at: http//www.oneM2M.org
The copyright and the foregoing restriction extend to reproduction in all media.
Notice of Disclaimer & Limitation of Liability
The information provided in this document is directed solely to professionals who have the appropriate degree of experience to understand and interpret its contents in accordance with generally accepted engineering or other professional standards and applicable regulations. No recommendation as to products or vendors is made or should be implied.
NO REPRESENTATION OR WARRANTY IS MADE THAT THE INFORMATION IS TECHNICALLY ACCURATE OR SUFFICIENT OR CONFORMS TO ANY STATUTE, GOVERNMENTAL RULE OR REGULATION, AND FURTHER, NO REPRESENTATION OR WARRANTY IS MADE OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR AGAINST INFRINGEMENT OF INTELLECTUAL PROPERTY RIGHTS. NO oneM2M PARTNER TYPE 1 SHALL BE LIABLE, BEYOND THE AMOUNT OF ANY SUM RECEIVED IN PAYMENT BY THAT PARTNER FOR THIS DOCUMENT, WITH RESPECT TO ANY CLAIM, AND IN NO EVENT SHALL oneM2M BE LIABLE FOR LOST PROFITS OR OTHER INCIDENTAL OR CONSEQUENTIAL DAMAGES. oneM2M EXPRESSLY ADVISES ANY AND ALL USE OF OR RELIANCE UPON THIS INFORMATION PROVIDED IN THIS DOCUMENT IS AT THE RISK OF THE USER.
<br/>Contents
# Scope
The present document provides a guide for application developers to use <subscription> resources in deployment:
- Description of the <subscription> resource features and capabilities in oneM2M,
- Description of how to use the <subscription> resource and procedures,
- Description of use cases that <subscription> can be used for,
- The call flows for implementation of the use cases described.
# References
## Normative references
Normative references are not applicable in the present document.
## Informative references
References are either specific (identified by date of publication and/or edition number or version number) or nonspecific. For specific references, only the cited version applies. For non-specific references, the latest version of the referenced document (including any amendments) applies.
The following referenced documents are not necessary for the application of the present document but they assist the user with regard to a particular subject area.
For the purposes of the present document, the terms and definitions given in oneM2M TS-0011 <ahref="#_ref_i.2">[i.2]</a> apply.
# Conventions
The key words "Shall", "Shall not", "May", "Need not", "Should", "Should not" in the present document are to be interpreted as described in the oneM2M Drafting Rules <ahref="#_ref_i.1">[i.1]</a>.
# Motivation
Devices generate data and send the data to a oneM2M CSE so that applications or processes can access the data without the need to directly communicate with the device. This simplifies the process for the application consuming data and the device generating the data. Applications can further benefit from simplified development by using oneM2M's subscribe-notify process, where an application can subscribe to receive notifications that indicate that there is a change to data of interest. This process has been demonstrated in other developer guides [x][y][z].
The <subscription> resource has other features that can offer additional benefits for applications that are interested in data hosted in the oneM2M CSE. This developer guide will describe the other features exposed by the oneM2M <subscription> resource and demonstrate some of those features using implementations of the oneM2M CSE that are available.
The features exposed by <subscription> resources also enhance capabilities of other oneM2M resources. For example there are enhancements related to <timeSeries>, <group>, and ????. There are also resources that enhance or modify the the <subscription> resource, such as <schedule>. These enhancements may be covered in future developer guides like this one.
# <subscription> Feature and Capabilities
## Creating and deleting a <subscription> resource
Before describing the advanced <subscription> capabilities it is important to cover the basic functionality. The most generic scenario is that there is data source generating data, such as an IoT device. The device measures or senses some physical aspect and sends the measurement values to the oneM2M CSE, shown in . There is also a companion application to monitor the sensed values from the device.
**Figure 6.5.1: Generic Use Case**
shows a resource tree structure for this use case where the device sends the measurement values in a <contentInstance> resource. The <contentInstance> resources are children of a <container> resource. Without the benefit of a subscribe-notify process, the companion application would have to periodically retrieve the <contentInstance> resources from the <container> resource. By creating a <subscription> resource as a child of the <container> the application can receive a notification from the oneM2M CSE each time the device creates a new <contentInstance> containing a new sensed value.
**Figure 6.5.1: Basic <subscription> use case**
The first requirement is to determine where notifications will be sent. There are two basic variations. The first variation is to set up an endpoint to receive a notification, which is very easy, quick to implement (use case 7.1.2) and useful for initial proof of concept implementations. See Github Repository.
The second variation is to specify an AE entity that will receive the notification. When specifying an AE to receive the notification, there are a couple additional benefits:
- When using an <AE> as the notification URI, a notification is sent to the address specified in the <AE> resource's pointOfContact attribute. This is helpful when the <AE> is to receive notifications from multiple <subscription> resources. If the pointofContact information changes, as is commonly the case with mobile or dynamic IP addresses, the IP address only needs to be updated in the <AE> pointOfContact as opposed to the notificationURI of each <subscription> resource that was created. See use case 7.1.3.
- When using an <AE> as the notification URI the option to use a long polling procedure to retrieve notifications is available. In this case the notification will be stored in the CSE until the AE entity retrieves the pollingChannelURI. This is used in cases where the AE does not have the ability to receive requests, such as when the entity is behind a firewall or the entity is a cellular IoT device where a requirement to receive a request is not recommended or some cases not supported. See use case 7.1.4.
In each of the ways the notification can be received, the minimum requirement when a NOTIFY request is received is that a response is sent with a oneM2M Response Status Code of 2000.
The next requirement for the creation of a <subscription> resource is having the proper authorizations granted in the "subscribed-to" resource. The originator of the CREATE <subscription> must have both CREATE and RETRIEVE permission for the "subscribed-to" resource. The CREATE permission is needed to create a child <subscription> resource and the RETRIEVE permission is needed because the NOTIFY request can contain a representation of the "subscribed-to" resource, as if it was retrieved.
The format of the notification request can be specified for each entity that will receive a notification. The examples in clause 7.1 use default setting that result in a JSON payload, but that can be modified. The <subscription> representation in shows a specific statement directing that the "non-oneM2M" entity that will receive notifications with XML payload. The other two values in the notificationURI are oneM2M entities, where the first AE is requestReachable and the second AE is not requestReachable and would use a <pollingChannel> resource to implement the long polling procedure.
**Table 6.1: <subscription> resource with different notificationURI**
```
{ ERRORS IN THIS
"": {
"": "mySubscription",
"": [
"",
"cse-in/Reachable-AE",
"cse-in/NonReachable-AE"
],
"su": "cse-in/Reachable-AE"
}
}
```
When a subscription request is received, if the required permissions are present, the Host CSE will send a "subscription verification request" to the entities in the notificationURI. As shown in the notification includes the subscriptionReference, which is the resource ID of the <subscription> that is to be created. It should be noted that if any of the notificationURI fail to respond then the <subscription> resource is not created.
**Table 6.1: notification verification request**
```
{
"m2m:sgn": {
"vrq": true,
"sur": "/id-in/sub338203473920864331",
"cr": "CDevGApp2"
}
}
```
When a "subscribed-to" resource is deleted all child <subscription> resources are also deleted. The <subscription> resource has a subscriberURI attribute that indicates the entity that will receive a notification that the <subscription> has been deleted. If the subscriberURI is specified the notification in would be received when the subscription is deleted.
**Table 6.1: notification with subscription deletion attribute**
```
{
"m2m:sgn": {
"sud": true,
"sur": "/id-in/sub338203473920864331"
}
}
```
## eventNotificationCriteria attributes
Most of the capabilities and functionality offered by the <subscription> resource are configured using the eventNotificationCriteria. The notificationEventType attribute is the most important in terms of configuring the different features of the <subscription> resource. This attribute is an array so that a single subscription can trigger a notification based on several conditions.
The first options for notificationEventType configure the CRUD operation that will trigger a notification:
****
**6.2**
|TS-0001 Value |TS-0004 Value |Behavior |
|-|-|-|
|A |1 |Update to attributes of the subscribed-to resource |
|B |2 |Deletion of the subscribed-to resource |
|C |3 |Creation of a direct child of the subscribed-to resource |
|D |4 |Deletion of a direct child of the subscribed-to resource |
The default value for notificationEventType, if not specified in the CREATE <subscription> request is <ahref="#_ref_1">[1]</a>(A). which sends a notification when the subscribed-to resource is modified. I am using the values defined in TS-0004 since they will be used in the example primitives shown in this document. For example, in the CREATE <subscription> shown in the notificationEventType was not specified, but the response shows the resource including its default setting in.
**6.2**
```
{
"m2m:sub": {
"rn": "mySubscription1",
"enc": {
"net": [
"",
"cse-in/Reachable-AE",
"cse-in/NonReachable-AE"
]
},
"su": "cse-in/Reachable-AE",
"ri": "sub834474148559106072",
"ct": "20220424T145442,675008",
"lt": "20220424T145442,675008",
"et": "20230424T145442,675036",
"exc": 23,
"nu": {
"net": [
1
]
},
"nct": 1
}
}
```
For the application scenario described in clause 6.1, the monitor application is displaying data from the <contentInstance> resources that are created as children of the subscribed-to resource, so the notificationEventType value of [1,3] (A and C) can be used to be notified of changes to the <container> and new <contentInstance> resources that are added. Additionally, the monitoring application ONLY needs notifications that <contentInstance> child resources are created. The childResourceType attribute is a list of resource types that will trigger a notification, when notificationEventType includes <ahref="#_ref_3">[3]</a>. Also, the monitoring application may only be interested in a subset of attributes of the subscribed-to resource. The attribute attribute of the <subscription> resource can contain a list of attributes that specify that only changes to the maxNrOfInstances attribute of the subscribed-to <container> should trigger a notification. All these configurations are demonstrated in .
****
**6.2**
```
{
"": {
"rn": "mySubscription2",
"": [
"cse-in/Reachable-AE"
],
"su": "cse-in/Reachable-AE",
"": {
"": [
1,
3
],
"chty": [
4
],
"atr": [
"mni"
]
}
}
}
```
Using the <subscription> configuration in will generate th notification when a <contentInstance> is and notification when the maxNrOfInstances attribute is updated in the <container> resource.
**6.2**
```
{
"m2m:sgn": {
"nev": {
"rep": {
"m2m:cin": {
"cnf": "text/plain:0",
"con": "Good news, everybody!",
"ri": "cin2567870597402199556",
"pi": "cnt7671567649274855615",
"rn": "cin_cevx3v3p2W",
"ct": "20220424T151328,044271",
"lt": "20220424T151328,044271",
"et": "20230424T151328,044298",
"ty": 4,
"cs": 21,
"st": 2
}
},
"net": 3
},
"sur": "/id-in/sub7828991872742761619"
}
}
```
In some use cases it is not necessary for the application to receive the entire payload of the resource that triggered the notification. The notificationContentType attribute can specify different representations in the notification, as shown in .
**Table6.2: Example of selected notificationContentTypes**
```
{
"1": {
"m2m:sgn": {
"nev": {
"rep": {
"m2m:cnt": {
"rn": "MySensorData",
"acpi": [
"acp3532889111641576504"
],
"ri": "cnt7671567649274855615",
"pi": "id-in",
"ct": "20220421T121634,227403",
"lt": "20220426T182525,916034",
"et": "20230421T121634,227430",
"ty": 3,
"cni": 4,
"cbs": 67,
"st": 18,
"mni": 10,
"mbs": 110
}
},
"net": 1
},
"sur": "/id-in/sub760458637602705614"
}
},
"2": {
"m2m:sgn": {
"nev": {
"rep": {
"m2m:cnt": {
"lt": "20220426T182745,275235",
"mni": 10
}
},
"net": 1
},
"sur": "/id-in/sub2537105913889510388"
}
},
"3": {
"m2m:sgn": {
"nev": {
"rep": {
"m2m:uri": "cnt7671567649274855615"
},
"net": 1
},
"sur": "/id-in/sub9053016274440701049"
}
}
}
```
There are other notificationEventType and eventNotificationCriteria settings, shown in and , that are related to more advanced features offered by oneM2M that are covered in separate documents.
**Table6.2: other notificationEventType settings**
|TS-0001 Value |Behavior |Notes |
|-|-|-|
|E |Retrieve obsolete <contentInstance> |This may be covered in a future update |
|F |Trigger received for an <AE> resource |Refer to Developer Guide for 3GPP interworking |
|G |Blocking Update |This will be covered in a future IPE / DM / actuator DEV GUIDE |
**Table6.2: other eventNotificationCriteria settings**
|TS-0001 Value |Behavior |Notes |
|-|-|-|
|operationMonitor |Notification when a configured operation is attempted, regardless of whether it request was successful or not. |This may be covered in a future update |
|missingData |Enhances <timeSeries> monitoring |Refer to Developer Guide for <timeSeries> |
|filterOperation |Specifies the logic operator (AND/OR/XOR) that should be applied for the following condition tags: createdBefore, createdAfter, <br/>modifiedSince, unmodifiedSince, stateTagSmaller, stateTagBigger, expireBefore,<br/>expireAfter, sizeAbove, sizeBelow |This may be covered in a future update |
## <crossResourceSubscription>
Normally a <subscription> resource sends notifications based on a single subscribed-to resource. In oneM2M there is support for notification of changes related to multiple different resources. Consider the use case depicted in Figure 3 that models a security application. In this scenario there can be subscriptions created to send notifications to the monitor application for every event that occurs in the monitored area. Then the monitor application can create state machines or some other logic to detect and report important events. For example, consider a scenario where we to know when a door is opened from inside a building. To determine if the door was opened from the inside there is a motion detector and a door opened sensor. If both sensors are triggered within a short period, that indicates that the door was opened from the inside. If the time between the notifications is too large, then this event is not of interest. If the events of interest occur, then an alarm (or light or camera) is turned on.
There are many ways that this can be implemented. In a first approach (number 1 in), this logic can be done by a monitoring application that receives all the notifications and then determines if the happen in the desired time frame. When the conditions are detected the application then sends a command to the device to turn on the alarm. This approach has multiple distributed applications that increase the overall complexity of the solution. In a second approach, the logic to detect the scenario is implemented on the Alarm device, but this increases the complexity and cost of the device. The third approach, enabled by oneM2M, allows for the configuration of a <crossResourceSubscription> that implements the desired logic and sends a notification to the Alarm (and any other entity as well). The result is much less complexity and cost for the deployment of this system.
**6.5.1**
****
The <crossResourceSubscription> for this approach can be configured in two ways. In the first and most generic approach, the <crossResourceSubscription> can be configured with the resources that are to be monitored, for example the motion sensor and the door sensor. If more complex <subscription> are needed, then they can be created separately and then the <crossResourceSubscription> is configured to monitor those existing <subscriptions>.
A <subscription> resource has the associatedCrossResourceSubscription attribute containing a reference to the monitoring by a <crossResourceSubscripton>. This attribute is not modifiable by an <AE> resource, only the CSE that hosts the <crossResourceSubscription> can modify this attribute.
In the third approach to the use case described above, first subscriptions to the containers where the sensor data is located are created. This is necessary because the subscriptions require childResourceType to be specified so that new <contentInstance> resources trigger the notification. Then specifying the resourceId of the <subscription> resources in the subscriptionResourceAsTarget attribute of the <crossResourceSubscription> and the desired window duration in timeWindowSize. This third approach has the advantages of less application code and faster response time than the other approaches.
****
**6.3**
```
{
"m2m:crs": {
"rn": "myCRSub1",
"srat": [
"sub9067376006991600376",
"sub4861910069341441770"
],
"twt": 2,
"tws": 1000,
"": [
"cse-in/Reachable-AE"
]
}
}
```
****
## Notification Statistics
Notification statistics can be captured for each <subscription>. The statistics will be collected if the notificationStatsEnable is set to True. When the statistics are collected, they can be viewed by retrieving the <subscription> resource and looking at the notificationStatsInfo attribute. The statistics can be reset by disabling and then reenabling the feature.
A <subscription> resource can have a child <schedule> resource that defines the times that notifications will be sent to the notificationURIs. When an event occurs that triggers a notification, and the time does not fall within the defined range(s) of the <schedule> resource then then notification may be cached by the CSE. The caching of notifications is configured using the pendingNotification attribute where all notifications from this <subscription> are stored or only the latest notification is stored or none of the notifications are stored. Other related attributes of the <subscription> resource are: batchNotify, rateLimit, notificationStoragePriority, latestNotify. Examples of this may appear in a future developer guide for <schedule> resources.
### <group> subscriptions
If an application creates a <subscription> resource using the fanoutpoint of a <group> resource, then the notificationForwardingURI can be used to have all notifications aggregated by the Host CSE. The subscriptions that are created in this manner, by a <group> hosting CSE, will set the groupID attribute of the <subscription> to the resource ID of the group resource. Examples of this may appear in a future developer guide for <group> resources.
### <timeSeries> subscriptions
Time series data has support in a oneM2M CSE to identify and notify a user of missing data. This functionality is configured using the missingData attribute of the <subscription> resource. Examples of this can be found in TR-XXXX.
### Notification handling when CMDH is supported
The CMDH features in oneM2M support communication using devices that may have intermittent or prioritized communication channels, such as a Cellular IoT device that only communicates with a oneM2M CSE according to a schedule to facilitate efficient communication patterns. This leads to messages, i.e. notifications, that are stored in a local CSE for some time before being transmitted. Since the occurrence of notifications is not deterministic there are parameters of the <subscription> resource that can help manage the storage and transmission of notifications. The effect of CMDH on notifications is similar to that related to the <schedule> resource described above and are configured with the same attributes: batchNotify, rateLimit, pendingNotification, notificationStoragePriority, latestNotify. Examples of this may appear in a future developer guide for CMDH features.
