switch-api 0.6.14__tar.gz → 0.6.16__tar.gz

{switch_api-0.6.14 → switch_api-0.6.16}/HISTORY.md

@@ -1,5 +1,25 @@
 # History
 
+#0.6.16
+### Changed
+In the `controls` module:
+- Updated `submit_control_continue()` to send log control requests to the IoT endpoint in chunks of 50 per request, improving reliability and preventing oversized payloads.
+- Updated `submit_control_continue()` to also batch control requests sent via MQTT (50 per batch), ensuring more stable and efficient message delivery.
+
+#0.6.15
+### Added
+In the `automation` module:
+- Added `send_cds_command()` to allow programmatic execution of CDS action commands (`Start`, `Stop`, `Restart`) for a specified data feed.
+- Added `deploy_as_cds_data_feed()` to support deployment of custom drivers as CDS-triggered data feeds with settings.
+- Added `deploy_as_webhooks_data_feed()` to enable deployment of custom drivers as webhook-triggered data feeds with support for client signing secrets, task priority, and framework configuration.
+
+In the `utils` module:
+- Added `ensure_uuid()` helper function to validate and normalize UUID inputs, supporting both `uuid.UUID` objects and UUID strings.
+
+### Modified
+In the `constants` module:
+- Extended `TASK_PRIORITY` to include new priority levels `control` and `lendlease-beot`.
+
 #0.6.14
 ### Modified
 In the `integration` module:

{switch_api-0.6.14 → switch_api-0.6.16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: switch_api
-Version: 0.6.14
+Version: 0.6.16
 Summary: A complete package for data ingestion into the Switch Automation Platform.
 Home-page: UNKNOWN
 Author: Switch Automation Pty Ltd.
@@ -38,6 +38,26 @@ pip install switch_api
 
 # History
 
+#0.6.16
+### Changed
+In the `controls` module:
+- Updated `submit_control_continue()` to send log control requests to the IoT endpoint in chunks of 50 per request, improving reliability and preventing oversized payloads.
+- Updated `submit_control_continue()` to also batch control requests sent via MQTT (50 per batch), ensuring more stable and efficient message delivery.
+
+#0.6.15
+### Added
+In the `automation` module:
+- Added `send_cds_command()` to allow programmatic execution of CDS action commands (`Start`, `Stop`, `Restart`) for a specified data feed.
+- Added `deploy_as_cds_data_feed()` to support deployment of custom drivers as CDS-triggered data feeds with settings.
+- Added `deploy_as_webhooks_data_feed()` to enable deployment of custom drivers as webhook-triggered data feeds with support for client signing secrets, task priority, and framework configuration.
+
+In the `utils` module:
+- Added `ensure_uuid()` helper function to validate and normalize UUID inputs, supporting both `uuid.UUID` objects and UUID strings.
+
+### Modified
+In the `constants` module:
+- Extended `TASK_PRIORITY` to include new priority levels `control` and `lendlease-beot`.
+
 #0.6.14
 ### Modified
 In the `integration` module:

{switch_api-0.6.14 → switch_api-0.6.16}/setup.py

@@ -16,7 +16,7 @@ setup(
     long_description_content_type='text/markdown',
     license='MIT License',
     name="switch_api",
-    version="0.6.14",
+    version="0.6.16",
     packages=find_packages(include=["switch_api", "switch_api.*"]),
     install_requires=['pandas==1.5.3', 'requests', 'azure-storage-blob', 'pandera[io]==0.7.1', 'azure-servicebus',
                       'msal>=1.11.0', 'paho-mqtt==1.6.1', 'uvicorn==0.22.0', 'fastapi==0.98.0', 'pyodbc==4.0.39', 'cachetools==5.5.0', 

{switch_api-0.6.14 → switch_api-0.6.16}/switch_api/__init__.py

@@ -42,4 +42,4 @@ from . import _guide
 # log.addHandler(_ch)
 # https://dev.to/joaomcteixeira/setting-up-python-logging-for-a-library-app-6ml
 
-__version__ = "0.6.14"
+__version__ = "0.6.16"

{switch_api-0.6.14 → switch_api-0.6.16}/switch_api/_utils/_constants.py

@@ -31,10 +31,10 @@ DATETIME_COL_FMT = Literal['DateTime', 'Date', 'Time']
 #  'Split year and month in 2 columns',
 #  'Start and End Date in 2 columns']
 
-EXPECTED_DELIVERY = Literal['5min', '15min', 'Hourly', 'Daily', 'Weekly', 'Monthly', 'Quarterly']
+EXPECTED_DELIVERY = Literal[ 'AdHoc', '1min', '5min', '15min', 'Hourly', 'Daily', 'Weekly', 'Monthly', 'Quarterly']
 
 # deploy_type 'File' for (FTP. Email, Upload)
-DEPLOY_TYPE = Literal['Email', 'Ftp', 'Upload', 'Timer']
+DEPLOY_TYPE = Literal['Email', 'Ftp', 'Upload', 'Timer', 'CDS']
 
 ACCOUNT = Literal['SwitchStorage', 'SwitchContainer', 'Argus', 'DataIngestion', 'GatewayMqttStorage']
 
@@ -45,11 +45,11 @@ QUERY_LANGUAGE = Literal['sql', 'kql']
 RESPONSE_TYPE = Literal['dataframe', 'json', 'string']
 
 ERROR_TYPE = Literal['DateTime', 'MissingDevices', 'NonNumeric', 'MissingRequiredField(s)', 'MissingSite(s)',
-                     'DuplicateRecords', 'MissingSensors', 'UnableToReadFile', 'InvalidFileType', 'InvalidInputSettings', 'ReadingSummariesTimeout']
+                     'DuplicateRecords', 'MissingSensors', 'UnableToReadFile', 'InvalidFileType', 'InvalidInputSettings', 'ReadingSummariesTimeout', 'InvalidDataType', 'NullValues']
 
 PROCESS_STATUS = Literal['ActionRequired', 'Failed']
 
-MAPPING_ENTITIES = Literal['Installations', 'Devices/Sensors', 'Readings', 'Work Orders', 'IQ']
+MAPPING_ENTITIES = Literal['Installations', 'Devices/Sensors', 'Readings', 'Work Orders', 'IQ', 'CustomData', 'Benchmarks']
 
 WORK_ORDER_CATEGORY = Literal['Preventative Maintenance', 'Tenant Request']
 
@@ -81,9 +81,9 @@ DATA_SET_QUERY_PARAMETER_TYPES = Literal['String', 'Number', 'DateTime', 'Keywor
 
 ADX_TABLE_DEF_TYPES = Literal['object', 'dynamic', 'int32', 'int64', 'float32', 'float64', 'datetime', 'string']
 
-TASK_PRIORITY = Literal['default', 'standard', 'advanced']
+TASK_PRIORITY = Literal['default', 'standard', 'advanced', 'control', 'lendlease-beot']
 
-TASK_FRAMEWORK = Literal['PythonScriptFramework', 'TaskInsightsEngine']
+TASK_FRAMEWORK = Literal['PythonScriptFramework', 'TaskInsightsEngine', 'CDSEngine']
 
 AMORTISATION_METHOD = Literal['Exclusive', 'Inclusive']
 
@@ -95,6 +95,8 @@ GUIDES_SCOPE = Literal['Portfolio-wide']
 
 IMPORT_STATUS = Literal['New', 'ToImport', 'OnHold', 'Exclude', 'Edited', 'ToRemove']
 
+CDS_ACTION_COMMAND = Literal["Start", "Stop", "Restart"]
+
 WS_DEFAULT_PORT = 443
 WS_MQTT_CONNECTION_TIMEOUT = 180
 WS_MQTT_DEFAULT_MAX_TIMEOUT = 180

{switch_api-0.6.14 → switch_api-0.6.16}/switch_api/_utils/_utils.py

@@ -521,3 +521,13 @@ def requests_retry_session2(retries: int = 5, status_forcelist: List[int] = [408
     session.mount('https://', adapter=adapter)
     session.retries = retries
     return session
+
+def ensure_uuid(value, field_name):
+    if isinstance(value, uuid.UUID):
+        return value
+    if isinstance(value, str):
+        try:
+            return uuid.UUID(value)
+        except ValueError:
+            pass
+    raise ValueError(f"{field_name} must be a valid UUID or UUID string.")

{switch_api-0.6.14 → switch_api-0.6.16}/switch_api/controls/controls.py

@@ -55,6 +55,43 @@ global _session
 _control_components = {}
 _switch_mqtt = None
 _session = None
+MAX_CONTROL_REQUEST_SENSORS = 50
+
+def _chunk_dataframe(df: pandas.DataFrame, chunk_size: int = MAX_CONTROL_REQUEST_SENSORS) -> List[pandas.DataFrame]:
+    """Split a dataframe into bounded chunks while preserving row order."""
+    if df.empty:
+        return []
+
+    return [
+        df.iloc[start_idx:start_idx + chunk_size].copy()
+        for start_idx in range(0, len(df), chunk_size)
+    ]
+
+def _build_chunk_session_ids(chunk_count: int, session_id: Union[uuid.UUID, str, None] = None) -> List[uuid.UUID]:
+    """Return one unique session id per chunk, reusing the provided id for the first chunk when valid."""
+    if chunk_count <= 0:
+        return []
+
+    chunk_session_ids: List[uuid.UUID] = []
+    seen_session_ids = set()
+
+    if is_valid_uuid(session_id):
+        first_session_id = uuid.UUID(str(session_id))
+    else:
+        first_session_id = uuid.uuid4()
+
+    chunk_session_ids.append(first_session_id)
+    seen_session_ids.add(str(first_session_id))
+
+    while len(chunk_session_ids) < chunk_count:
+        next_session_id = uuid.uuid4()
+        if str(next_session_id) in seen_session_ids:
+            continue
+
+        chunk_session_ids.append(next_session_id)
+        seen_session_ids.add(str(next_session_id))
+
+    return chunk_session_ids
 
 def submit_control_continue(api_inputs: ApiInputs, data: pandas.DataFrame, information_columns: list = [], 
                             is_send_control: bool = True, ws_timeout_in_seconds: int = WS_MQTT_CONNECTION_TIMEOUT):
@@ -409,39 +446,70 @@ def __send_control(api_inputs: ApiInputs, installation_id: Union[uuid.UUID, str]
     acknowledgement_df = format_acknowledgement_payload_df(
         df=acknowledgement_df, required_columns=required_columns, has_priority=has_priority)
 
+    control_request_df = control_request_df.copy()
+    control_request_df = format_control_payload_df(
+        required_columns=required_columns, has_priority=has_priority, df=control_request_df)
+
+    acknowledgement_chunks = _chunk_dataframe(acknowledgement_df)
+    control_request_chunks = _chunk_dataframe(control_request_df)
+    chunk_session_ids = _build_chunk_session_ids(
+        chunk_count=len(control_request_chunks),
+        session_id=session_id)
+
     if is_send_control:
-        _, result_df = log_control_request(
-            session=_session,
-            api_inputs=api_inputs, 
-            df=acknowledgement_df, 
-            session_id=session_id, 
-            installation_id=installation_id)
-        if result_df.empty:
+        if len(acknowledgement_chunks) != len(control_request_chunks):
+            logger.error("Chunk count mismatch between control acknowledgement and MQTT payloads.")
             df_matrix[COL_CONTROL_STATUS] = ControlStatus.NotSentToService.value
             return df_matrix
 
-    control_request_df = control_request_df.copy()
-    control_request_df = format_control_payload_df(
-        required_columns=required_columns, has_priority=has_priority, df=control_request_df)
+        successful_ack_chunks = []
+        successful_control_chunks = []
+        successful_session_ids = []
+
+        for acknowledgement_chunk, control_request_chunk, chunk_session_id in zip(
+            acknowledgement_chunks,
+            control_request_chunks,
+            chunk_session_ids,
+        ):
+            _, result_df = log_control_request(
+                session=_session,
+                api_inputs=api_inputs,
+                df=acknowledgement_chunk,
+                session_id=chunk_session_id,
+                installation_id=installation_id,
+            )
 
-    def process_paged_request(df, page_size: int = 20):
-        paged_results = pandas.DataFrame()
-        total_rows = len(df)
-        num_pages = (total_rows + page_size - 1) // page_size
+            if result_df.empty:
+                logger.warning(
+                    "Skipping failed chunk for session_id=%s",
+                    chunk_session_id,
+                )
+                continue
 
-        for page_num in range(num_pages):
-            start_idx = page_num * page_size
-            end_idx = min((page_num + 1) * page_size, total_rows)
+            successful_ack_chunks.append(acknowledgement_chunk)
+            successful_control_chunks.append(control_request_chunk)
+            successful_session_ids.append(chunk_session_id)
 
-            # Get the data for the current page
-            page_data = df.iloc[start_idx:end_idx]
+        #only successfuly chunks are used for the control request next
+        acknowledgement_chunks = successful_ack_chunks
+        control_request_chunks = successful_control_chunks
+        chunk_session_ids = successful_session_ids
 
-            result = send_control(page_data)
+        if not acknowledgement_chunks:
+            logger.error("All chunks failed during log control request.")
+            df_matrix[COL_CONTROL_STATUS] = ControlStatus.NotSentToService.value
+            return df_matrix
+            
+    def process_paged_request(chunks: List[pandas.DataFrame], chunk_session_ids: List[uuid.UUID]):
+        paged_results = pandas.DataFrame()
+
+        for page_data, chunk_session_id in zip(chunks, chunk_session_ids):
+            result = send_control(page_data, chunk_session_id)
             paged_results = pandas.concat([paged_results, result])
 
         return paged_results
 
-    def send_control(page_data):
+    def send_control(page_data: pandas.DataFrame, chunk_session_id: uuid.UUID):
         retry_count = 0
         max_retries = 3
         success_results = pandas.DataFrame()
@@ -451,7 +519,7 @@ def __send_control(api_inputs: ApiInputs, installation_id: Union[uuid.UUID, str]
 
         while retry_count < max_retries:
             success_response, missing_response = _switch_mqtt.send_control_request(
-                session_id=str(session_id),
+                session_id=str(chunk_session_id),
                 installation_id=installation_id,
                 sensors=dataframe_to_control.to_dict(orient='records'))
 
@@ -522,7 +590,7 @@ def __send_control(api_inputs: ApiInputs, installation_id: Union[uuid.UUID, str]
         return control_result
 
     if is_send_control:
-        control_results = process_paged_request(control_request_df)
+        control_results = process_paged_request(control_request_chunks, chunk_session_ids)
         control_results = control_results.rename(
             columns={'sensorId': COL_OBJECT_PROPERTY_ID})
         control_results = pandas.merge(control_results, df_matrix[[
@@ -673,12 +741,18 @@ def submit_control(api_inputs: ApiInputs, installation_id: Union[uuid.UUID, str]
     if _session == None:
         _session = requests_retry_session2(retries=5, backoff_factor=2)
 
-    _, result_df = log_control_request(session=_session, 
-                        api_inputs=api_inputs, 
-                        df=data_frame, 
-                        session_id=session_id, 
-                        installation_id=installation_id)
-    if result_df.empty:
+    acknowledgement_chunks = _chunk_dataframe(data_frame)
+    chunk_session_ids = _build_chunk_session_ids(
+        chunk_count=len(acknowledgement_chunks),
+        session_id=session_id)
+
+    for acknowledgement_chunk, chunk_session_id in zip(acknowledgement_chunks, chunk_session_ids):
+        _, result_df = log_control_request(session=_session,
+                            api_inputs=api_inputs,
+                            df=acknowledgement_chunk,
+                            session_id=chunk_session_id,
+                            installation_id=installation_id)
+        if result_df.empty:
             return pandas.DataFrame()
 
     # Proceeds when the control request is successful
@@ -722,24 +796,18 @@ def submit_control(api_inputs: ApiInputs, installation_id: Union[uuid.UUID, str]
         logger.info("Could not connect to MQTT Broker.")
         return 'Could not connect to MQTT Broker.', pandas.DataFrame()
 
-    def process_paged_request(df, page_size: int = 20):
-        paged_results = pandas.DataFrame()
-        total_rows = len(df)
-        num_pages = (total_rows + page_size - 1) // page_size
-
-        for page_num in range(num_pages):
-            start_idx = page_num * page_size
-            end_idx = min((page_num + 1) * page_size, total_rows)
+    control_request_chunks = _chunk_dataframe(data_frame)
 
-            # Get the data for the current page
-            page_data = df.iloc[start_idx:end_idx]
+    def process_paged_request(chunks: List[pandas.DataFrame], chunk_session_ids: List[uuid.UUID]):
+        paged_results = pandas.DataFrame()
 
-            result = send_control(page_data)
+        for page_data, chunk_session_id in zip(chunks, chunk_session_ids):
+            result = send_control(page_data, chunk_session_id)
             paged_results = pandas.concat([paged_results, result])
 
         return paged_results
 
-    def send_control(page_data):
+    def send_control(page_data: pandas.DataFrame, chunk_session_id: uuid.UUID):
         retry_count = 0
         max_retries = 3
         success_results = pandas.DataFrame()
@@ -749,7 +817,7 @@ def submit_control(api_inputs: ApiInputs, installation_id: Union[uuid.UUID, str]
 
         while retry_count < max_retries:
             success_response, missing_response = _switch_mqtt.send_control_request(
-                session_id=str(session_id),
+                session_id=str(chunk_session_id),
                 installation_id=installation_id,
                 sensors=dataframe_to_control.to_dict(orient='records'))
 
@@ -821,7 +889,7 @@ def submit_control(api_inputs: ApiInputs, installation_id: Union[uuid.UUID, str]
     
     # [Subscribe] to ClientId + Site State Topics
     _switch_mqtt.subscribe_installation(installation_id=installation_id)
-    control_results = process_paged_request(data_frame)
+    control_results = process_paged_request(control_request_chunks, chunk_session_ids)
 
     return control_results
  
@@ -983,6 +1051,8 @@ def log_control_request(session: requests.Session, api_inputs: ApiInputs, df: pa
     logger.info("Control Request Session Id: %s", session_id)
     logger.info("Control Request for User: %s=%s",
                 api_inputs.email_address, api_inputs.user_id)
+    logger.info("Log Control Request Payload:")
+    logger.info(json_payload)
     
     try:
         response = session_post(session, url, json_payload, headers)
@@ -1177,4 +1247,4 @@ def session_post(session, url, json_payload, headers):
         if "Connection refused" in str(ex):
             logger.error("Hard failure: Connection Refused. Not retrying.")
             raise
-        raise
+        raise

{switch_api-0.6.14 → switch_api-0.6.16}/switch_api/pipeline/__init__.py

@@ -75,13 +75,13 @@ functions for retrieving details of existing tasks on the Switch Automation Plat
 """
 
 from .pipeline import (IntegrationTask, QueueTask, LogicModuleTask, AnalyticsTask, DiscoverableIntegrationTask,
-                       EventWorkOrderTask, BlobTask, Guide, IQTask, logger)
+                       EventWorkOrderTask, BlobTask, Guide, IQTask, CDSTask, logger)
 from .automation import Automation
 from .definitions import (IntegrationDeviceConfigPropertyDefinition, IntegrationDeviceDefinition,
                           AnalyticsSettings, EventWorkOrderFieldDefinition, IntegrationSettings)
 
 
 __all__ = ['IntegrationTask', 'QueueTask', 'LogicModuleTask', 'AnalyticsTask', 'DiscoverableIntegrationTask',
-           'EventWorkOrderTask', 'BlobTask', 'Guide', 'IQTask', 'Automation', 'logger', 'IntegrationDeviceConfigPropertyDefinition',
+           'EventWorkOrderTask', 'BlobTask', 'Guide', 'IQTask', 'CDSTask', 'Automation', 'logger', 'IntegrationDeviceConfigPropertyDefinition',
            'IntegrationDeviceDefinition', 'EventWorkOrderFieldDefinition',
            'AnalyticsSettings', 'IntegrationSettings']

{switch_api-0.6.14 → switch_api-0.6.16}/switch_api/pipeline/automation.py

@@ -23,12 +23,12 @@ import sys
 import uuid
 from io import StringIO
 from azure.servicebus import ServiceBusClient, ServiceBusReceiveMode
-from .._utils._utils import _is_valid_regex, ApiInputs, _column_name_cap, DataFeedFileProcessOutput
+from .._utils._utils import _is_valid_regex, ApiInputs, _column_name_cap, DataFeedFileProcessOutput, ensure_uuid
 from .._utils._marketplace import add_marketplace_item
-from .._utils._constants import (argus_prefix, EXPECTED_DELIVERY, MAPPING_ENTITIES,
+from .._utils._constants import (CDS_ACTION_COMMAND, argus_prefix, EXPECTED_DELIVERY, MAPPING_ENTITIES,
                                  QUEUE_NAME, ERROR_TYPE, SCHEDULE_TIMEZONE, DEPLOY_TYPE, TASK_PRIORITY, TASK_FRAMEWORK, GUIDES_EXTERNAL_TYPES, GUIDES_SCOPE)
 from .._utils._platform import _get_ingestion_service_bus_connection_string, Blob
-from .pipeline import (Task, QueueTask, IntegrationTask, LogicModuleTask, AnalyticsTask, EventWorkOrderTask,
+from .pipeline import (CDSTask, Task, QueueTask, IntegrationTask, LogicModuleTask, AnalyticsTask, EventWorkOrderTask,
                        DiscoverableIntegrationTask, BlobTask, Guide, IQTask)
 from ..extensions import ExtensionTask, replace_extensions_imports, has_extensions_support
 from .definitions import (IntegrationDeviceDefinition, EventWorkOrderFieldDefinition, AnalyticsSettings,
@@ -1040,6 +1040,227 @@ class Automation:
         df.columns = _column_name_cap(df.columns)
 
         return df
+    
+    @staticmethod
+    def deploy_as_cds_data_feed(task: Task,
+                                api_inputs: ApiInputs, 
+                                data_feed_id: uuid.UUID,
+                                expected_delivery: EXPECTED_DELIVERY,
+                                settings: dict = {},
+                                data_feed_name: str = None):
+        """
+
+        Parameters
+        ----------
+        task : Task
+            The custom driver class created from the Abstract Base Class 'Task'
+        api_inputs : ApiInputs
+            Object returned by the initialize() function.
+        data_feed_id : uuid.UUID
+            The DataFeedId to update if existing, else will create a new record with the given value.
+        expected_delivery : EXPECTED_DELIVERY
+            The expected delivery frequency of the data.
+        data_feed_name : str, Optional
+            The name of the data feed (to be displayed in Task Insights UI). If not provided, will default to the
+            task name.
+        settings : dict
+            List of settings used to deploy the driver. May containing information needed to access 3rd party api
+             - e.g. URI, Username, Pwd, AccessToken, etc
+
+        Returns
+        -------
+        df : pandas.DataFrame
+            Dataframe containing the details of the deployed https endpoint data feed.
+
+        """
+        if not isinstance(task, CDSTask):
+            logger.error(f"deploy_as_cds_data_feed only accepts tasks that implement CDSTask, got {type(task).__name__}")
+            return pandas.DataFrame()
+
+        if api_inputs.api_base_url == '' or api_inputs.bearer_token == '':
+            logger.error("You must call initialize() before using API.")
+            return pandas.DataFrame()
+
+        if data_feed_id is None and data_feed_name is None:
+            data_feed_id = uuid.UUID('00000000-0000-0000-0000-000000000000')
+            data_feed_name = task.__class__.__qualname__
+        elif data_feed_id is not None and data_feed_name is None:
+            data_feed_id = data_feed_id
+            data_feed_name = data_feed_name
+            
+        if not set([expected_delivery]).issubset(set(EXPECTED_DELIVERY.__args__)):
+            logger.error('expected_delivery parameter must be set to one of the allowed values defined by the '
+                         'EXPECTED_DELIVERY literal: %s', EXPECTED_DELIVERY.__args__)
+            return pandas.DataFrame()
+        
+        if settings and not isinstance(settings, dict):
+            logger.error("setting parameter should be of type dict.")
+            return pandas.DataFrame()
+
+        headers = api_inputs.api_headers.default
+
+        logger.info('Deploy %s (%s) as a data feed for ApiProjectID: %s', type(task).__name__, str(task.id), api_inputs.api_project_id)
+        
+        task_framework: TASK_FRAMEWORK = 'CDSEngine'
+        task_priority: TASK_PRIORITY = 'standard'
+
+        logger.info('Task Framework is "%s"', str(task_framework))
+        logger.info('Task Priotiy is "%s"', str(task_priority))
+
+        payload = {
+            "driverId": str(task.id),
+            "dataFeedId": str(data_feed_id),
+            "name": data_feed_name,
+            "feedType": "CDS",
+            "sourceType": "CDS",
+            "expectedDelivery": expected_delivery,
+            "taskFramework": task_framework,
+            "taskPriority": task_priority,
+            "settings": settings
+        }
+
+        url = f"{api_inputs.api_projects_endpoint}/{api_inputs.api_project_id}/data-ingestion/tasks/deployment"
+
+        logger.info("Sending request: POST %s", url)
+
+        response = requests.post(url, json=payload, headers=headers)
+        response_status = '{} {}'.format(response.status_code, response.reason)
+        if response.status_code != 200:
+            logger.error("API Call was not successful. Response Status: %s. Reason: %s.", response.status_code,
+                         response.reason)
+            return response_status, pandas.DataFrame()
+        elif len(response.text) == 0:
+            logger.error('No data returned for this API call. %s', response.request.url)
+            return response_status, pandas.DataFrame()
+
+        df = pandas.read_json(StringIO(response.text), typ='Series').to_frame().T
+        df.columns = _column_name_cap(df.columns)
+
+        return df
+
+    @staticmethod
+    def deploy_as_webhooks_data_feed(task: Task,
+                                   api_inputs: ApiInputs, 
+                                   data_feed_id: uuid.UUID,
+                                   client_signing_secret: str,
+                                   expected_delivery: EXPECTED_DELIVERY,
+                                   settings: dict = {},
+                                   data_feed_name: str = None,
+                                   task_priority: TASK_PRIORITY = 'standard',
+                                   task_framework: TASK_FRAMEWORK = 'TaskInsightsEngine'):
+        
+        """Deploy the custom driver as a Webhook triggered Data Feed.
+
+        Parameters
+        ----------
+        task : Task
+            The custom driver class created from the Abstract Base Class 'Task'
+        api_inputs : ApiInputs
+            Object returned by the initialize() function.
+        data_feed_id : uuid.UUID
+            The DataFeedId to update if existing, else will create a new record with the given value.
+        client_signing_secret : uuid.UUID
+            Client Signing Secret 
+        expected_delivery : EXPECTED_DELIVERY
+            The expected delivery frequency of the data.
+        queue_name : QUEUE_NAME, optional
+            The queue name (Default value = 'task').
+        data_feed_name : str, Optional
+            The name of the data feed (to be displayed in Task Insights UI). If not provided, will default to the
+            task name.
+        task_priority: TASK_PRIORITY
+            Determines the priority of the datafeed tasks when processing. This equates to how much resources would be alloted
+            to run the task - 'default`, 'standard', or 'advanced'. Defaults to 'default'.
+        task_framework: TASK_FRAMEWORK
+            Determines the framework of the datafeed tasks when processing.
+            'PythonScriptFramework' for the old task runner engine.
+            'TaskInsightsEngine' for the new task running in container apps.
+        settings : dict
+            List of settings used to deploy the driver. May containing information needed to access 3rd party api
+             - e.g. URI, Username, Pwd, AccessToken, etc
+
+        Returns
+        -------
+        df : pandas.DataFrame
+            Dataframe containing the details of the deployed webhook endpoint data feed.
+
+        """
+
+        if api_inputs.api_base_url == '' or api_inputs.bearer_token == '':
+            logger.error("You must call initialize() before using API.")
+            return pandas.DataFrame()
+
+        if data_feed_id is None and data_feed_name is None:
+            data_feed_id = uuid.UUID('00000000-0000-0000-0000-000000000000')
+            data_feed_name = task.__class__.__qualname__
+        elif data_feed_id is not None and data_feed_name is None:
+            data_feed_id = data_feed_id
+            data_feed_name = data_feed_name
+
+        if client_signing_secret == '' or client_signing_secret == None:
+            logger.error("Client Signing Secret cannot be null.")
+            return pandas.DataFrame()
+
+        headers = api_inputs.api_headers.default
+
+        if not set([expected_delivery]).issubset(set(EXPECTED_DELIVERY.__args__)):
+            logger.error('expected_delivery parameter must be set to one of the allowed values defined by the '
+                         'EXPECTED_DELIVERY literal: %s', EXPECTED_DELIVERY.__args__)
+            return pandas.DataFrame()
+
+        if not set([task_framework]).issubset(set(TASK_FRAMEWORK.__args__)):
+            logger.error('task_framework parameter must be set to one of the allowed values defined by the '
+                         'TASK_FRAMEWORK literal: %s', TASK_FRAMEWORK.__args__)
+            return pandas.DataFrame()
+
+        if not set([task_priority]).issubset(set(TASK_PRIORITY.__args__)):
+            logger.error('task_priority parameter must be set to one of the allowed values defined by the '
+                         'TASK_PRIORITY literal: %s', TASK_PRIORITY.__args__)
+            return pandas.DataFrame()
+        
+        if settings and not isinstance(settings, dict):
+            logger.error("setting parameter should be of type dict.")
+            return pandas.DataFrame()
+
+        logger.info('Deploy %s (%s) as a data feed for ApiProjectID: %s', type(task).__name__, str(task.id),
+                    api_inputs.api_project_id)
+        logger.info('Task Framework is "%s"', str(task_framework))
+        logger.info('Task Priotiy is "%s"', str(task_priority))
+
+        payload = {
+            "dataFeedId": str(data_feed_id),
+            "driverId": str(task.id),
+            "name": data_feed_name,
+            "feedType": "Webhooks",
+            "expectedDelivery": expected_delivery,
+            "sourceType": "Webhooks",
+            "taskFramework": task_framework,
+            "taskPriority": task_priority,
+            "webhook": {
+                "clientSigningSecret": client_signing_secret
+            },
+            "settings": settings
+        }
+
+        url = f"{api_inputs.api_projects_endpoint}/{api_inputs.api_project_id}/data-ingestion/tasks/deployment"
+
+        logger.info("Sending request: POST %s", url)
+
+        response = requests.post(url, json=payload, headers=headers)
+        response_status = '{} {}'.format(response.status_code, response.reason)
+
+        if response.status_code != 200:
+            logger.error("API Call was not successful. Response Status: %s. Reason: %s.", response.status_code,
+                         response.reason)
+            return response_status, pandas.DataFrame()
+        elif len(response.text) == 0:
+            logger.error('No data returned for this API call. %s', response.request.url)
+            return response_status, pandas.DataFrame()
+
+        df = pandas.read_json(StringIO(response.text), typ='Series').to_frame().T
+        df.columns = _column_name_cap(df.columns)
+
+        return df
 
     @staticmethod
     def deploy_as_blob_data_feed(task: BlobTask,
@@ -1377,6 +1598,10 @@ class Automation:
         # Check if there's any timer deploy_type being cancelled, delete it as well by calling delete method
         if any("Timer" in deploy_type for deploy_type in deployment_type):
             return Automation.delete_deployed_data_feed(api_inputs=api_inputs, data_feed_id=data_feed_id)
+        
+        # Check if there's any CDS deploy_type being cancelled, send `STOP` action command by calling send_cds_command()
+        if any("CDS" in deploy_type for deploy_type in deployment_type):
+            return Automation.send_cds_command(api_inputs=api_inputs, data_feed_id=data_feed_id, action_command='Stop')
 
         df = pandas.read_json(response.text, typ='Series').to_frame().T
         df.columns = _column_name_cap(df.columns)
@@ -1385,7 +1610,8 @@ class Automation:
 
     @staticmethod
     def delete_deployed_data_feed(api_inputs: ApiInputs, data_feed_id: uuid.UUID):
-        """Delete deployment for a given `data_feed_id`.
+        """
+        Delete timer schedule for a given `data_feed_id`.
 
         Parameters
         ----------
@@ -1813,3 +2039,111 @@ class Automation:
         task_code += 'task = ' + task_type.__name__ + '()'
 
         return task_code
+
+    @staticmethod
+    def send_cds_command(
+            api_inputs: ApiInputs,
+            data_feed_id: uuid.UUID,
+            action_command: CDS_ACTION_COMMAND):
+        """Send a CDS action command for a given data feed.
+
+        This method sends a POST request to the CDS action-command endpoint for the
+        specified data feed. It validates the required API inputs and command values
+        before building the request payload and submitting it to the API.
+
+        Parameters
+        ----------
+        api_inputs : ApiInputs
+            Object returned by the initialize.initialize() function. This must contain
+            a valid ``api_base_url``, ``bearer_token``, ``api_project_id``,
+            ``api_projects_endpoint``, and default request headers.
+        data_feed_id : uuid.UUID
+            The unique identifier of the data feed that the CDS command will be sent to.
+        action_command : CDS_ACTION_COMMAND
+            The action command to execute for the target data feed. This must be set
+            to one of the allowed literal values defined by ``CDS_ACTION_COMMAND``.
+
+        Returns
+        -------
+        pandas.DataFrame
+            A dataframe containing the API response when the request is successful.
+
+        tuple[str, pandas.DataFrame]
+            Returns a tuple of ``(response_status, empty_dataframe)`` when the API call
+            is not successful.
+
+        pandas.DataFrame
+            Returns an empty dataframe when API inputs are not initialized or when no
+            data is returned from the API.
+
+        Raises
+        ------
+        ValueError
+            Raised when:
+            - ``api_inputs`` is None
+            - ``data_feed_id`` is not a valid ``uuid.UUID``
+            - ``action_command`` is not one of the allowed ``CDS_ACTION_COMMAND`` values
+
+        Notes
+        -----
+        This method performs the following steps:
+
+        1. Validates the required inputs.
+        2. Builds the request payload using the API project ID, data feed ID,
+            and action command.
+        3. Sends a POST request to the CDS action-command API endpoint.
+        4. Converts the JSON response into a single-row pandas dataframe.
+        5. Normalizes the dataframe column names using ``_column_name_cap``.
+
+        Examples
+        --------
+        >>> df = sw.pipeline.Automation._send_cds_command(
+        ...     api_inputs=api_inputs,
+        ...     data_feed_id=uuid.UUID("12345678-1234-1234-1234-123456789abc"),
+        ...     action_command="Start"
+        ... )
+
+        """
+
+        # ensure data_feed_id is UUID
+        data_feed_id = ensure_uuid(data_feed_id, "data_feed_id")
+
+        # Validate api_inputs
+        if api_inputs is None:
+            raise ValueError("api_inputs cannot be None.")
+
+        if not api_inputs.api_base_url or not api_inputs.bearer_token:
+            logger.error("You must call initialize() before using API.")
+            return pandas.DataFrame()
+
+        # Validate enums/literals
+        if action_command not in CDS_ACTION_COMMAND.__args__:
+            raise ValueError('action_command parameter must be set to one of the allowed values defined by the '
+                         'CDS_ACTION_COMMAND literal: %s', CDS_ACTION_COMMAND.__args__)
+        
+        payload = {
+            "apiProjectId": api_inputs.api_project_id,
+            "dataFeedId": str(data_feed_id),
+            "actionCommand": action_command
+        }
+
+        url = f"{api_inputs.api_projects_endpoint}/{api_inputs.api_project_id}/data-ingestion/data-feed/{data_feed_id}/cds/action-command"
+
+        logger.info("Sending request: POST %s", url)
+
+        headers = api_inputs.api_headers.default
+        response = requests.post(url, json=payload, headers=headers)
+        response_status = '{} {}'.format(response.status_code, response.reason)
+
+        if response.status_code != 200:
+            logger.error("API Call was not successful. Response Status: %s. Reason: %s.", response.status_code,
+                         response.reason)
+            return response_status, pandas.DataFrame()
+        elif len(response.text) == 0:
+            logger.error('No data returned for this API call. %s', response.request.url)
+            return response_status, pandas.DataFrame()
+
+        df = pandas.read_json(StringIO(response.text), typ='Series').to_frame().T
+        df.columns = _column_name_cap(df.columns)
+
+        return df

{switch_api-0.6.14 → switch_api-0.6.16}/switch_api/pipeline/pipeline.py

@@ -621,6 +621,16 @@ class LogicModuleTask(Task):
 
     # Needs to be implemented into the deploy_on_timer
 
+class CDSTask(Task):
+    """
+    Base class for long-running CDS driver tasks.
+
+    Implement process_loop() for continuous execution / polling / worker-style behavior.
+    """
+
+    @abstractmethod
+    def process_loop(self, api_inputs, settings):
+        pass
 
 class RunAt(enum.Enum):
     """ """

{switch_api-0.6.14 → switch_api-0.6.16}/switch_api.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: switch-api
-Version: 0.6.14
+Version: 0.6.16
 Summary: A complete package for data ingestion into the Switch Automation Platform.
 Home-page: UNKNOWN
 Author: Switch Automation Pty Ltd.
@@ -38,6 +38,26 @@ pip install switch_api
 
 # History
 
+#0.6.16
+### Changed
+In the `controls` module:
+- Updated `submit_control_continue()` to send log control requests to the IoT endpoint in chunks of 50 per request, improving reliability and preventing oversized payloads.
+- Updated `submit_control_continue()` to also batch control requests sent via MQTT (50 per batch), ensuring more stable and efficient message delivery.
+
+#0.6.15
+### Added
+In the `automation` module:
+- Added `send_cds_command()` to allow programmatic execution of CDS action commands (`Start`, `Stop`, `Restart`) for a specified data feed.
+- Added `deploy_as_cds_data_feed()` to support deployment of custom drivers as CDS-triggered data feeds with settings.
+- Added `deploy_as_webhooks_data_feed()` to enable deployment of custom drivers as webhook-triggered data feeds with support for client signing secrets, task priority, and framework configuration.
+
+In the `utils` module:
+- Added `ensure_uuid()` helper function to validate and normalize UUID inputs, supporting both `uuid.UUID` objects and UUID strings.
+
+### Modified
+In the `constants` module:
+- Extended `TASK_PRIORITY` to include new priority levels `control` and `lendlease-beot`.
+
 #0.6.14
 ### Modified
 In the `integration` module: