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,17 @@
+---
+date:
+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:
+---
+Streaming Analytics can now use the {{< product-c8y-iot >}} Notifications 2.0 reliable data forwarding capability to receive update notifications on new measurements, events, alarms, managed objects and operations that are processed by the {{< product-c8y-iot >}} platform. This feature is currently in private preview, so to take advantage of it, you must contact {{< product-c8y-iot >}} Operations to set the `notification2.streaming-analytics` feature flag. In addition, users of any of the variants of the Apama-ctrl microservice also need to toggle the `streaming-analytics.messaging` feature flag. All users of both Apama-ctrl and custom microservices must also add the `ROLE_NOTIFICATION_2_ADMIN` permission to the microservice manifest. Users of external Apama deployments must add the new **Cumulocity Notifications 2.0** bundle to their Apama projects. 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
 ---
@@ -38,4 +38,10 @@ The manifest also specifies the permissions with which the microservice runs. Th
 - ROLE_BULK_OPERATION_ADMIN
 - ROLE_BULK_OPERATION_READ
 
+{{< c8y-admon-info>}}
+To take advantage of the {{< product-c8y-iot >}} Notifications 2.0 reliable data forwarding capability to receive update notifications, you must also add the following permission to the manifest of the Apama-ctrl microservice and contact {{< product-c8y-iot >}} Operations to set the the `notification2.streaming-analytics` feature flag.
+
+- ROLE_NOTIFICATION_2_ADMIN
+{{< /c8y-admon-info>}}
+
 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,51 @@
+---
+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 update notifications on new 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://www.cumulocity.com/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-c8y-iot >}} Operations 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.
+    <!-- For further information on these feature flags and on feature flags in general, see (TODO: this doc has not yet been written). -->
+
+{{< c8y-admon-info>}}
+If you are using either a custom microservice or an Apama project, it is not necessary to use the `streaming-analytics.messaging` feature flag. Using this flag does not change anything for a custom microservice or Apama project. See also the description of the **Cumulocity Notifications 2.0** bundle in [Step 3 - Add Apama bundles to the project](/streaming-analytics/epl-apps/#step-3---add-apama-bundles-to-the-project).
+{{< /c8y-admon-info>}}
+
+Once the required feature flags have been activated, whatever microservice you are using, you must also add the `ROLE_NOTIFICATION_2_ADMIN` permission to the microservice manifest. For more information, see [Modifying microservice permissions and resource usage](/streaming-analytics/analytics-customization/#microservice-permissions) for the Apama-ctrl microservices and [Required settings in the microservice manifest](/streaming-analytics/epl-apps/#required-settings-in-the-microservice-manifest) for custom microservices.
+
+### Toggling the streaming-analytics.messaging feature flag using the REST API
+
+If you are using one of the standard Apama-ctrl microservices, you must also set the `streaming-analytics.messaging` flag to activate how the microservice receives notifications. You do this using the REST API as shown below.
+
+To find all existing feature toggles for the current tenant, together with their values, make a `GET` request to this endpoint:
+
+```http
+/features
+```
+
+To find out the existing feature toggle for the `streaming-analytics.messaging` feature flag for the current tenant, make a `GET` request to this endpoint:
+
+```http
+/features/streaming-analytics.messaging
+```
+
+To toggle the `streaming-analytics.messaging` feature flag for the current tenant, make a `PUT` request to this endpoint:
+
+```http
+/features/streaming-analytics.messaging/by-tenant
+```
+
+To toggle the `streaming-analytics.messaging` feature flag for the specified tenant ID, make a `PUT` request to this endpoint:
+
+```http
+/features/streaming-analytics.messaging/by-tenant/{tenant-id}
+```
+
+Keep in mind that you must also resubscribe the microservice to pick up changes to the feature flag.

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

@@ -57,7 +57,7 @@ From this page, you can:
 ##### Step 2 - Create an EPL app {#step-2---create-an-epl-app}
 
 Click **New EPL app** in the top menu bar. In the resulting **Create app** dialog box, enter a unique app name.
-You can also enter a description which will be shown on the card that is created for the new app. Click **OK**. 
+You can also enter a description which will be shown on the card that is created for the new app. Click **OK**.
 
 The EPL editor appears. The EPL code for the new app already contains the typical basic event definitions and utilities that are required for working with {{< product-c8y-iot >}}. You can adapt them as required for your app. Consult the documentation and samples for more details.
 
@@ -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 IoT > 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](https://documentation.softwareag.com/pam/10.15.5/en/webhelp/pam-webhelp/#page/pam-webhelp%2Fco-ConApaAppToExtCom_cumulocity_receiving_update_notifications.html) 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](https://documentation.softwareag.com/pam/10.15.5/en/webhelp/pam-webhelp/#page/pam-webhelp%2Fco-ApaRelNot_10155_migrate-to-notifications.html) 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 update notifications, you must also add the following permission to the manifest of the custom microservice and contact {{< product-c8y-iot >}} Operations 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 >}}