PAB-4250: Add info on Notifications 2.0 to the Streaming Analytics doc

content/change-logs/analytics/apama-in-c8y-20240902-Notifications-2.0.md

@@ -0,0 +1,21 @@
+---
+date: 2025-01-07
+title: Streaming Analytics and Notifications 2.0
+change_type:
+  - value: change-QHu1GdukP
+    label: Feature
+product_area: Analytics
+component:
+  - value: component-M5-cepIIS
+    label: Streaming Analytics
+build_artifact:
+  - value: tc-KXXmo2SUR
+    label: apama-in-c8y
+ticket: PAB-4250
+version: 25.339.0
+---
+Streaming Analytics can now use the {{< product-c8y-iot >}} Notifications 2.0 reliable data forwarding capability to receive notifications for measurements, events, alarms, managed objects and operations that are processed by the {{< product-c8y-iot >}} platform. The benefits of using Notifications 2.0 are improved performance and reliability for messaging with Streaming Analytics applications such as smart rules, Analytics Builder and EPL apps.
+
+Streaming Analytics intends to migrate all tenants to use Notifications 2.0, and some customers may choose to start migrating now. This change is intended to provide improved performance, reliability and resilience in planned future enhancements to Streaming Analytics.
+
+This feature is currently in private preview. To take advantage of it, you must contact [product support](/additional-resources/contacting-support/) to set the `notification2.streaming-analytics` feature flag. In addition, users of any of the variants of the Apama-ctrl microservice must also toggle the `streaming-analytics.messaging` feature flag. Users of custom Apama microservices must also add the `ROLE_NOTIFICATION_2_ADMIN` permission to the microservice manifest. Users of custom Apama EPL projects must also add the new **Cumulocity Notifications 2.0** bundle. Apama EPL projects that remotely connect to Cumulocity IoT via the long-polling interface will benefit from improved robustness after migrating to Notifications 2.0. For more information, including how to toggle the feature flags, see [Configuration requirements for Notifications 2.0](/streaming-analytics/analytics-customization/#notifications).

content/streaming-analytics/analytics-customization-bundle/microservice-permissions.md

@@ -1,5 +1,5 @@
 ---
-weight: 40
+weight: 50
 title: Modifying microservice permissions and resource usage
 layout: redirect
 ---
@@ -37,5 +37,6 @@ The manifest also specifies the permissions with which the microservice runs. Th
 - ROLE_TENANT_MANAGEMENT_READ
 - ROLE_BULK_OPERATION_ADMIN
 - ROLE_BULK_OPERATION_READ
+- ROLE_NOTIFICATION_2_ADMIN
 
 You can add other roles to this list (or remove them from it) to grant (or remove) permissions to EPL code.

content/streaming-analytics/analytics-customization-bundle/notifications.md

@@ -0,0 +1,23 @@
+---
+weight: 40
+title: Configuration requirements for Notifications 2.0
+layout: redirect
+---
+Streaming Analytics can use the {{< product-c8y-iot >}} Notifications 2.0 reliable data forwarding capability to receive notifications for measurements, events, alarms, managed objects and operations that are processed by the {{< product-c8y-iot >}} platform. For more information, see [About Notifications 2.0](https://{{< domain-c8y >}}/api/core/#tag/About-notifications-2.0) in the {{< openapi >}}.
+
+The availability of this feature is governed by two feature flags:
+
+- `notification2.streaming-analytics` <br>
+    The {{< product-c8y-iot >}} Notifications 2.0 feature is currently in private preview. If you want to have it enabled for your tenant, you must contact [product support](/additional-resources/contacting-support/) to set this feature flag.
+
+- `streaming-analytics.messaging` <br>
+    In addition to this, if you are using one of the variants of the Apama-ctrl microservice, you must also set this feature flag. You then need to resubscribe the Apama-ctrl microservice to pick up changes to the feature flag.
+    Use the feature toggles REST API to do so; see [Feature toggles API](https://{{< domain-c8y >}}/api/core/#tag/Feature-toggles-API) in the {{< openapi >}}.
+    <!-- For further information on these feature flags and on feature flags in general, see (TODO: this doc has not yet been written). -->
+
+If you are using a custom microservice, you must also add the `ROLE_NOTIFICATION_2_ADMIN` permission to the microservice manifest once the `notification2.streaming-analytics` feature flag has been activated; see also [Required settings in the microservice manifest](/streaming-analytics/epl-apps/#required-settings-in-the-microservice-manifest).
+For the Apama-ctrl microservices, it is not required to add this permission manually as it is set as the default; see also [Modifying microservice permissions and resource usage](/streaming-analytics/analytics-customization/#microservice-permissions).
+
+{{< c8y-admon-info >}}
+Keep in mind that you must also resubscribe the microservice to pick up changes to the feature flag.
+{{< /c8y-admon-info >}}

content/streaming-analytics/epl-apps-bundle/basic-functionality.md

@@ -125,9 +125,14 @@ Exposes predefined generic events used by the HTTP client connectivity plug-in.
 This starts all connectivity plug-ins immediately on start up.
 * **HTTP Client > JSON with generic request/response event definitions** <br>
 Allows EPL apps to make HTTP calls.
-* **Cumulocity > Cumulocity Client** <br>
-Exposes the {{< product-c8y-iot >}} client to EPL apps.
+* **Cumulocity IoT > Cumulocity Notifications 2.0** <br>
+Exposes the {{< product-c8y-iot >}} client to EPL apps using the Notifications 2.0 mechanism.
+For general information on how to receive {{< product-c8y-iot >}} update notifications, see [Receiving update notifications]({{< link-apama-webhelp >}}/standard-connectivity-plugins/the-cumulocity-iot-transport-connectivity-plug-in#receiving-update-notifications) in the Apama documentation.
 
+{{< c8y-admon-info >}}
+The **Cumulocity Notifications 2.0** connectivity bundle has been added for receiving notifications from {{< product-c8y-iot >}} using the Notifications 2.0 mechanism. The existing **Cumulocity Client** connectivity bundle that uses the legacy long-polling mechanism is deprecated in favor of this new bundle. In addition, it is now possible to add the **Cumulocity REST Support** connectivity bundle if you do not receive any notifications. You must only add one of these three bundles to your project.
+For information on how to migrate existing Apama projects to Notifications 2.0, see [Migrating from Cumulocity Client to Cumulocity Notifications 2.0]({{< link-apama-webhelp >}}/change-logs/#10.15/cumulocity-10155-clientbundledeprecated) in the Apama documentation.
+{{< /c8y-admon-info >}}
 
 The bundles above are the only ones that are permissible in an EPL app, so be careful not to add any other bundles or your app may not work when activated in {{< product-c8y-iot >}}.
 
@@ -241,6 +246,12 @@ The following permissions are required by the microservice in order to start up
 - ROLE_BULK_OPERATION_READ
 - ROLE_SMS_ADMIN
 
+{{< c8y-admon-info>}}
+To take advantage of the {{< product-c8y-iot >}} Notifications 2.0 reliable data forwarding capability to receive notifications, you must also add the following permission to the manifest of the custom microservice and contact [product support](/additional-resources/contacting-support/) to set the the `notification2.streaming-analytics` feature flag.
+
+- ROLE_NOTIFICATION_2_ADMIN
+{{< /c8y-admon-info>}}
+
 {{< c8y-admon-info >}}
 The above is the minimum list of permissions that a custom Apama microservice needs. If you are developing a custom microservice, you may add more permissions to the microservice manifest.
 {{< /c8y-admon-info >}}