06-notifications.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img style=\"float: right; padding: 10px;\" width=\"200\" src=\"images/logo-onem2m-the-iot-standard.jpg\">\n",
    "\n",
    "# oneM2M - Subscriptions and Notifications\n",
    "\n",
    "This notebook demonstrates how to subscribe to notifications from resources.\n",
    "\n",
    "<p>\n",
    "<div  style=\"background-color:transparent;border:2px #005480 solid;padding: 10px;width: calc(100% - 350px);border-radius:10px;\">\n",
    "    <div style=\"color:#005480;\"><b><i class=\"fa fa-info-circle\" aria-hidden=\"true\"></i>&nbsp; Note</b></div>\n",
    "    <div style=\"color:#545054;\">\n",
    "Please execute the notebook \"oneM2M - Subscriptions and Notifications - Notification Server\" from the <a href=\"start-notificationServer.ipynb\">notification server notebook</a> first.<br>\n",
    "This starts a notification server that will receive the notifications that result from the following requests.\n",
    "<br>\n",
    "If you later see an error like \"internal server errror\" and a <i>Result Status Code</i> of <i>5204</i> you most likely forget to start the notification server. Please open the <a href=\"start-notificationServer.ipynb\">notification server notebook</a> and run or restart the server.    </div>\n",
    "</div>\n",
    "</p>\n",
    "\n",
    "- Create a &lt;subscription> resource\n",
    "- Create &lt;contentInstance> resource and receive a notification\n",
    "\n",
    "\n",
    "## Intitialization\n",
    "The section does import necessary modules and configurations, and prepares the CSE for this notebook.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%run src/init.py subscriptions"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "tags": []
   },
   "source": [
    "## Subscribe to a &lt;container> Resource\n",
    "\n",
    "<img align=\"right\" src=\"images/06/create_subscription.png\">\n",
    "\n",
    "\n",
    "\n",
    "The following requests creates a &lt;subscription> resource for the *Container* resource.\n",
    "\n",
    "<p>\n",
    "<div style=\"background-color:transparent;border:2px #b42025 solid;padding: 10px;width: calc(100% - 600px);border-radius:10px;\">\n",
    "    <div style=\"color:#b42025;\"><b><i class=\"fa fa-info-circle\" aria-hidden=\"true\"></i>&nbsp; oneM2M</b></div>\n",
    "    <div style=\"color:#545054;\">\n",
    "&lt;subscription> resource are used to monitor resource creations, updates and more. They also carry the configuration when and how the notifications are sent to a notification target.\n",
    "<br /><br />\n",
    "Please note, that instead of specifying a direct URL in the &lt;subscription> we usually set an &lt;AE> resource as a target for a notification and then specify the URL in the &lt;AE>'s <i>point-of-access</i> (poa) attribute. This has the advantage that an &lt;AE> is in control of its notification endpoint instead of each &lt;subscription> resource.\n",
    "    </div>\n",
    "</div>\n",
    "</p> \n",
    "\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "CREATE (                                           # CREATE request\n",
    "    \n",
    "    # Create subscription resource under the container\n",
    "    to                      = cseBaseName + '/StreetLight-AE-2/Light-Container-2',  \n",
    "    \n",
    "    # Request Parameters\n",
    "    originator              = 'CstreetLight-AE-1', # Set the originator\n",
    "    requestIdentifier       = '123',               # Unique request identifier\n",
    "    releaseVersionIndicator = '3',                 # Release version indicator\n",
    "    resourceType            = Type.Subscription,   # Type of the resource: Subscription\n",
    "    \n",
    "    # Request Body\n",
    "    primitiveContent = \n",
    "        {\n",
    "            'm2m:Subscription': {\n",
    "                'resourceName'  : 'Subscription',\n",
    "                'notificationURI'  : [ notificationURL ],\n",
    "                'notificationContentType' : 1,\n",
    "                'eventNotificationCriteria' : {\n",
    "                    'notificationEventType': [ 1, 2, 3, 4 ]\n",
    "                }\n",
    "            }\n",
    "        }\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Please check the [Notification Server](start-notificationServer.ipynb) notebook** (the one with the running Notification Server) to see the verification request.  \n",
    "When this requests returns with a *201 (Created)* status code / *2001 oneM2M Response Status Code* then the creation of the &lt;subscription> resource as well as the verification request were successfull.\n",
    "\n",
    "<p>\n",
    "<div  style=\"background-color:transparent;border:2px #005480 solid;padding: 10px;width: calc(100% - 600px);border-radius:10px;\">\n",
    "    <div style=\"color:#005480;\"><b><i class=\"fa fa-info-circle\" aria-hidden=\"true\"></i>&nbsp; Note</b></div>\n",
    "    <div style=\"color:#545054;\">\n",
    "    If you see an error like \"Verification request failed\" or \"internal server errror\" and a <i>Response Status Code</i> of 5204 you most likely forget to start the notification server. Please open the <a href=\"start-notificationServer.ipynb\">notification server</a> notebook and run the server.<br>\n",
    "    <b>Then you need to execute the above cell again!</b>    \n",
    "    </div>\n",
    "</div>\n",
    "</p>\n",
    "\n",
    "<p>\n",
    "<div style=\"background-color:transparent;border:2px #b42025 solid;padding: 10px;width: calc(100% - 600px);border-radius:10px;\">\n",
    "    <div style=\"color:#b42025;\"><b><i class=\"fa fa-info-circle\" aria-hidden=\"true\"></i>&nbsp; oneM2M</b></div>\n",
    "    <div style=\"color:#545054;\">\n",
    "        A <i>verification request</i> is used by the CSE to verify that the target is reachable and willing to receive notifications. Any failure or rejection by the target server leads to a rejection of the CREATE request of the &lt;subscription>.\n",
    "    </div>\n",
    "</div>\n",
    "</p>\n",
    "\n",
    "\n",
    "### Requests & Response Attributes\n",
    "\n",
    "The request and response introduce new attributes:\n",
    "\n",
    "| Attribute                 | Short Name | Description                                                                                                                                     |\n",
    "|:--------------------------|:-----------|:------------------------------------------------------------------------------------------------------------------------------------------------|\n",
    "| notificationURI           | nu         | The Notification URI specifies where to send verification and notification requests. This could be an entity, like an &lt;AE>, or a direct URL. |\n",
    "| eventNotificationCriteria | enc        | The configuration for the &lt;subscription> that specifies when to send a event.                                                                |\n",
    "| notificationContentType   | nct        | The Notification Content Type attribute specifies the kind of content that should be sent in a notification initiated by this subscription.     |\n",
    "| notificationEventType     | net        | A list of Notification Event Types indicates the reason when a notification is sent.                                                            |\n",
    "| notificationStatsEnable   | nse        | Record statistics per target how many notifications have been sent.                                                                             |\n",
    "| notificationStatsInfo     | nsi        | A list of notification statistics per target.                                                                                                   |\n",
    "| notification              | sgn        | A notification request structure.                                                                                                               |\n",
    "| verificationRequest       | vrq        | Indicator that a notification is a so-called verification request.                                                                              |\n",
    "| subscriptionReference     | sur        | The resource ID of the subscription for the notification request.                                                                               |\n",
    "| creator                   | cr         | The originator of a request that caused the notification.                                                                                       |\n",
    "\n",
    "\n",
    "#### Values for Notification Content Type\n",
    "\n",
    "| Value | Interpretation                           |\n",
    "|:------|:-----------------------------------------|\n",
    "| 1     | All. The whole resource                  |\n",
    "| 2     | Only modified attributes                 |\n",
    "| 3     | The resource's *resource ID*             |\n",
    "| 4     | The trigger payload in case of Triggers  |\n",
    "\n",
    "\n",
    "#### Notification Event Types\n",
    "\n",
    "\n",
    "| Value | Interpretation                                        |\n",
    "|:------|:------------------------------------------------------|\n",
    "| 1     | Update of Resource                                    |\n",
    "| 2     | Delete of Resource                                    |\n",
    "| 3     | Create of Direct Child Resource                       |\n",
    "| 4     | Delete of Direct Child Resource                       |\n",
    "| 5     | Retrieve of Container Resource With No Child Resource |\n",
    "| 6     | Trigger Received For AE_Resource                      |\n",
    "| 7     | Blocking Update                                       |\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img align=\"right\" src=\"images/06/create_contentInstance.png\">\n",
    "\n",
    "\n",
    "## Add a &lt;contentInstance> Resource to Light-Container and Send a Notification\n",
    "\n",
    "We now have subscribed to a status change, i.e. whenever a child resource is added to the &lt;container>.\n",
    "For example, when Streetlight-AE-2 receives a new command under this container, then a notification is raised by the &lt;subscription> resource.\n",
    "\n",
    "This is shown with the following request. To simplify he example the AE \"StreetLight-AE-1\" is the reques sender."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "CREATE (                                             # CREATE request\n",
    "    \n",
    "    # Add the <container> under the <AE>\n",
    "    to                      = cseBaseName + '/StreetLight-AE-2/Light-Container-2',\n",
    "    \n",
    "    # Request Parameters\n",
    "    originator              = 'CstreetLight-AE-1',   # Set the originator\n",
    "    requestIdentifier       = '123',                 # Unique request identifier\n",
    "    releaseVersionIndicator = '3',                   # Release version indicator\n",
    "    resourceType            = Type.ContentInstance,  # Type of the resource (ContentInstance)\n",
    "    \n",
    "    # Request Body\n",
    "    primitiveContent = \n",
    "        {\n",
    "            'm2m:ContentInstance' : {\n",
    "                'contentInfo' : 'text/plain:0',\n",
    "                'content' : 'lights on'\n",
    "            }\n",
    "        }\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "tags": []
   },
   "source": [
    "**Again, please check the [Notification Server](start-notificationServer.ipynb) notebook to see the notification.** \n",
    "\n",
    "\n",
    "<p>\n",
    "<div style=\"background-color:transparent;border:2px #b42025 solid;padding: 10px;width: calc(100% - 600px);border-radius:10px;\">\n",
    "    <div style=\"color:#b42025;\"><b><i class=\"fa fa-info-circle\" aria-hidden=\"true\"></i>&nbsp; oneM2M</b></div>\n",
    "    <div style=\"color:#545054;\">\n",
    "This request and result are similar as the previously request when we added a &lt;container> resource. But when we look at the output in the <a href=\"start-notificationServer.ipynb\">Notification Server</a> notebook, we see that the notification contains the same resource as this request. This way any receiver of a notification can react to a change of a resource without polling a CSE.<br>\n",
    "This behaviour can be changed when configuring the &lt;subscription> resource.    </div>\n",
    "</div>\n",
    "</p>\n",
    "\n",
    "Any further creation of a &lt;contentInstance> resource will cause a new notification to be sent.\n",
    "\n",
    "\n",
    "### Requests & Response Attributes\n",
    "\n",
    "The request and response introduce new attributes:\n",
    "\n",
    "| Attribute                 | Short Name | Description                                                                                                                                     |\n",
    "|:--------------------------|:-----------|:------------------------------------------------------------------------------------------------------------------------------------------------|\n",
    "| notificationEvent | nev | The notification request contains a notification event. |\n",
    "| representation | rep | Representation for the notification as it was configured with the &lt;subscription>'s <i>notificationContentType</i> attribute. |\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "&nbsp;"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.8.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}