feat: Add GENERICSYSTEMEVENT support to RealTimeEvent enum and RealTimeEventListener

docsrc/markdown/datafeed.md

@@ -197,7 +197,8 @@ datahose:
     eventTypes: # mandatory field, events you want to receive
         - INSTANTMESSAGECREATED
         - ROOMCREATED
-        - ROOMUPDATED 
+        - ROOMUPDATED
+        - GENERICSYSTEMEVENT
 
     retry: # optional
         maxAttempts: 6 # maximum number of retry attempts
@@ -206,10 +207,10 @@ datahose:
         maxIntervalMillis: 10000 # limit of the interval between two attempts
 ```
 
-The minimal configuration for the datahose service is the `eventTypes` field. It should contain at least one value 
-chosen among [_Real Time Events_](https://docs.developers.symphony.com/building-bots-on-symphony/datafeed/real-time-events) 
-list and that `MESSAGESENT`, `MESSAGESUPPRESSED` and `SYMPHONYELEMENTSACTION` values can be set only if the ceservice is
-properly configured and running in your Symphony agent.
+The minimal configuration for the datahose service is the `eventTypes` field. It should contain at least one value
+chosen among [_Real Time Events_](...) list. Note that `MESSAGESENT`, `MESSAGESUPPRESSED`, `SYMPHONYELEMENTSACTION`
+and `GENERICSYSTEMEVENT` values can be set only if the ceservice is properly configured and running in your
+Symphony agent.
 
 The `tag` field is optional and is used when creating and reusing datahose feeds. If you have several instances of the
 same bot and want them to use the same datahose feed (so that events are spread over bot instances),

examples/datafeed/datahose_generic_system_event.py

@@ -0,0 +1,68 @@
+import asyncio
+import logging
+import logging.config
+from pathlib import Path
+
+from symphony.bdk.core.config.loader import BdkConfigLoader
+from symphony.bdk.core.service.datafeed.real_time_event_listener import RealTimeEventListener
+from symphony.bdk.core.symphony_bdk import SymphonyBdk
+from symphony.bdk.gen.agent_model.v4_generic_system_event import V4GenericSystemEvent
+from symphony.bdk.gen.agent_model.v4_initiator import V4Initiator
+
+# Required config.yaml datahose section:
+#
+# datahose:
+#   tag: my-bot-tag
+#   eventTypes:
+#     - GENERICSYSTEMEVENT
+
+
+async def run():
+    config = BdkConfigLoader.load_from_symphony_dir("config.yaml")
+
+    async with SymphonyBdk(config) as bdk:
+        datahose_loop = bdk.datahose()
+        datahose_loop.subscribe(RealTimeEventListenerImpl())
+        await datahose_loop.start()
+
+
+class RealTimeEventListenerImpl(RealTimeEventListener):
+    async def on_generic_system_event(self, initiator: V4Initiator, event: V4GenericSystemEvent):
+        """Called for every GENERICSYSTEMEVENT received from the datahose.
+
+        GENERICSYSTEMEVENT is a platform-level envelope emitted by Symphony's internal
+        Maestro event bus. The ``event_subtype`` field identifies the specific event;
+        ``parameters`` carries subtype-specific data whose structure varies per subtype.
+
+        Always filter on ``event_subtype`` — do not act on every generic event blindly.
+        """
+        subtype = event.event_subtype
+
+        # We do not recommend logging full events in production as it could expose sensitive data
+        logging.debug("GenericSystemEvent received — subtype: %s", subtype)
+
+        # Filter on the specific subtype relevant to your use case.
+        # The subtype values are defined by your Symphony deployment; log them first
+        # to discover which ones are relevant before adding conditional logic.
+        if subtype == "CONNECTION_REQUEST_ALERT":
+            # Example: a federation connection lifecycle event.
+            # event.parameters contains subtype-specific fields.
+            logging.info("Connection request alert — parameters: %s", event.parameters)
+
+        elif subtype is None:
+            logging.warning("Received GENERICSYSTEMEVENT with no event_subtype — skipping")
+
+        else:
+            logging.debug("Unhandled GENERICSYSTEMEVENT subtype: %s", subtype)
+
+
+logging.config.fileConfig(
+    Path(__file__).parent.parent / "logging.conf", disable_existing_loggers=False
+)
+
+
+try:
+    logging.info("Running datahose generic system event example...")
+    asyncio.run(run())
+except KeyboardInterrupt:
+    logging.info("Ending datahose generic system event example")

symphony/bdk/core/service/datafeed/abstract_datafeed_loop.py

@@ -57,6 +57,7 @@ class RealTimeEvent(Enum):
     CONNECTIONACCEPTED = ("on_connection_accepted", "connection_accepted")
     SYMPHONYELEMENTSACTION = ("on_symphony_elements_action", "symphony_elements_action")
     MESSAGESUPPRESSED = ("on_message_suppressed", "message_suppressed")
+    GENERICSYSTEMEVENT = ("on_generic_system_event", "generic_system_event")
 
 
 def _set_context_var(current_task, event, listener):
@@ -202,7 +203,8 @@ async def _run_listener_method(listener: RealTimeEventListener, event: V4Event):
             listener_method_name, payload_field_name = RealTimeEvent[event.type].value
         except KeyError:
             logger.info("Received event with an unknown type: %s", event.type)
-            return
+            return # <-- GENERICSYSTEMEVENT hits this branch
+            # GENERICSYSTEMEVENT is not in the enum, so every event is dropped.
 
         listener_method = getattr(listener, listener_method_name)
         event_field = getattr(event.payload, payload_field_name)

symphony/bdk/core/service/datafeed/real_time_event_listener.py

@@ -1,3 +1,4 @@
+from symphony.bdk.gen.agent_model.v4_generic_system_event import V4GenericSystemEvent
 from symphony.bdk.gen.agent_model.v4_connection_accepted import V4ConnectionAccepted
 from symphony.bdk.gen.agent_model.v4_connection_requested import V4ConnectionRequested
 from symphony.bdk.gen.agent_model.v4_event import V4Event
@@ -166,3 +167,20 @@ async def on_symphony_elements_action(
         :param initiator: Event initiator.
         :param event: Symphony Elements Action payload.
         """
+
+    async def on_generic_system_event(
+        self, initiator: V4Initiator, event: V4GenericSystemEvent
+    ):
+        """
+        Called when a GENERICSYSTEMEVENT event is received.
+
+        Generic system events are platform-level notifications emitted by Symphony's internal Maestro event bus.
+        The ``event_subtype`` field on the payload identifies the specific event; ``parameters`` carries
+        subtype-specific data.
+
+        Bot developers should filter on ``event.event_subtype`` rather than relying solely on the outer
+        ``GENERICSYSTEMEVENT`` type.
+
+        :param initiator: Event initiator.
+        :param event: Generic system event payload (``V4GenericSystemEvent``).
+        """

tests/core/service/datafeed/abstract_datafeed_loop_test.py

@@ -1,6 +1,7 @@
 # ruff: noqa
 import asyncio
 from unittest.mock import AsyncMock, call, patch
+from symphony.bdk.gen.agent_model.v4_generic_system_event import V4GenericSystemEvent
 
 import pytest
 
@@ -492,6 +493,22 @@ async def test_handle_symphony_element(df_loop, listener, initiator_userid):
         initiator_userid, payload.symphony_elements_action
     )
 
+# This test verifies the full dispatch path: enum lookup → payload extraction → listener method called with correct
+# arguments
+@pytest.mark.asyncio
+async def test_handle_generic_system_event(df_loop, listener, initiator_userid):
+    payload = V4Payload(generic_system_event=V4GenericSystemEvent())
+    event = V4Event(
+        type=RealTimeEvent.GENERICSYSTEMEVENT.name,
+        payload=payload,
+        initiator=initiator_userid,
+    )
+
+    await create_and_await_tasks(df_loop, [event])
+
+    listener.on_generic_system_event.assert_called_once_with(
+        initiator_userid, payload.generic_system_event
+    )
 
 @pytest.mark.asyncio
 async def test_handle_unknown_type(df_loop, listener, initiator_userid):