fix:PRComments

Author: RSam-NI

docs/api_reference.rst

@@ -8,6 +8,7 @@ API Reference
    :caption: Table of Contents
 
    api_reference/core
+   api_reference/alarm
    api_reference/tag
    api_reference/product
    api_reference/testmonitor

docs/api_reference/alarm.rst

@@ -0,0 +1,19 @@
+.. _api_alarm_page:
+
+nisystemlink.clients.alarm
+==========================
+
+.. autoclass:: nisystemlink.clients.alarm.AlarmClient
+   :exclude-members: __init__
+
+   .. automethod:: __init__
+   .. automethod:: create_or_update_alarm
+   .. automethod:: get_alarm
+   .. automethod:: delete_alarm
+   .. automethod:: delete_instances_by_instance_id
+   .. automethod:: acknowledge_alarm
+   .. automethod:: query_alarms
+
+.. automodule:: nisystemlink.clients.alarm.models
+   :members:
+   :imported-members:

docs/getting_started.rst

@@ -3,6 +3,55 @@
 Getting Started
 ===============
 
+Alarm API
+---------
+
+Overview
+~~~~~~~~
+
+The :class:`.AlarmClient` class is the primary entry point of the Alarm API.
+
+When constructing an :class:`.AlarmClient`, you can pass an
+:class:`.HttpConfiguration` (like one retrieved from the
+:class:`.HttpConfigurationManager`), or let :class:`.AlarmClient` use the
+default connection. The default connection depends on your environment.
+
+With an :class:`.AlarmClient` object, you can:
+
+* Create and update alarm instances using :meth:`~.AlarmClient.create_or_update_alarm`
+
+  * Alarms have two key identifiers:
+  
+    * ``alarm_id``: A user-defined identifier for the alarm type
+    * ``instance_id``: A server-generated unique identifier for each alarm occurrence
+  
+  * Create alarm transitions (SET, CLEAR) to track alarm state changes
+
+* Query alarms with :meth:`~.AlarmClient.query_alarms`
+
+  * Filter alarms using Dynamic LINQ expressions
+  * Control which transitions are returned (most recent only or all)
+  * Sort and paginate results
+
+* Get a specific alarm by its instance_id using :meth:`~.AlarmClient.get_alarm`
+
+* Acknowledge alarms with :meth:`~.AlarmClient.acknowledge_alarm`
+
+  * Optionally force-clear alarms when acknowledging
+
+* Delete alarms using :meth:`~.AlarmClient.delete_alarm` or 
+  :meth:`~.AlarmClient.delete_instances_by_instance_id`
+
+Examples
+~~~~~~~~
+
+Create, query, acknowledge, and delete alarms
+
+.. literalinclude:: ../examples/alarm/alarm.py
+   :language: python
+   :linenos:
+
+
 Tag API
 -------
 

examples/alarm/alarm.py

@@ -3,7 +3,6 @@
 
 from nisystemlink.clients.alarm import AlarmClient
 from nisystemlink.clients.alarm.models import (
-    AcknowledgeByInstanceIdRequest,
     CreateOrUpdateAlarmRequest,
     QueryWithFilterRequest,
 )
@@ -25,6 +24,7 @@
 client = AlarmClient(configuration=server_configuration)
 
 # Create a unique alarm ID for this example
+# alarm_id is a user-defined identifier for this alarm
 alarm_id = f"example_alarm_{uuid.uuid1().hex}"
 
 # Create an alarm with a SET transition
@@ -38,13 +38,13 @@
         message="Temperature sensor reading: 85°C",
     ),
 )
-create_response = client.create_or_update_alarm(create_request)
-instance_id = create_response.instance_id
+# Returns instance_id - a server-generated unique identifier for this specific alarm occurrence
+id = client.create_or_update_alarm(create_request)
 
-# Get the alarm by instance ID
-alarm = client.get_alarm(instance_id)
+# Get the alarm by its instance ID (the unique occurrence identifier)
+alarm = client.get_alarm(id)
 
-# Update the alarm with a higher severity
+# Update the alarm with a higher severity (same alarm_id, updates the same instance)
 update_request = CreateOrUpdateAlarmRequest(
     alarm_id=alarm_id,
     transition=CreateAlarmTransition(
@@ -55,9 +55,9 @@
         message="Temperature sensor reading: 95°C",
     ),
 )
-update_response = client.create_or_update_alarm(update_request)
+client.create_or_update_alarm(update_request)
 
-# Query alarms with a filter
+# Query alarms with a filter (can filter by alarm_id to find all instances)
 query_request = QueryWithFilterRequest(
     filter=f'alarmId="{alarm_id}"',
     transition_inclusion_option=TransitionInclusionOption.ALL,
@@ -67,9 +67,8 @@
 )
 query_response = client.query_alarms(query_request)
 
-# Acknowledge the alarm
-ack_request = AcknowledgeByInstanceIdRequest(instance_ids=[instance_id])
-ack_response = client.acknowledge_instances_by_instance_id(ack_request)
+# Acknowledge the alarm using its instance ID
+ack_response = client.acknowledge_alarm([id])
 
 # Clear the alarm
 clear_request = CreateOrUpdateAlarmRequest(
@@ -81,7 +80,7 @@
         condition="Temperature returned to normal",
     ),
 )
-clear_response = client.create_or_update_alarm(clear_request)
+client.create_or_update_alarm(clear_request)
 
-# Delete the alarm by instance ID
-client.delete_alarm(instance_id)
+# Delete the alarm by its instance ID
+client.delete_alarm(id)

nisystemlink/clients/alarm/_alarm_client.py

@@ -5,7 +5,7 @@
 from nisystemlink.clients import core
 from nisystemlink.clients.core._uplink._base_client import BaseClient
 from nisystemlink.clients.core._uplink._methods import delete, get, post
-from uplink import retry
+from uplink import Field, retry
 
 from . import models
 
@@ -16,6 +16,7 @@
     on_exception=retry.CONNECTION_ERROR,
 )
 class AlarmClient(BaseClient):
+
     def __init__(self, configuration: Optional[core.HttpConfiguration] = None):
         """Initialize an instance.
 
@@ -26,92 +27,107 @@ def __init__(self, configuration: Optional[core.HttpConfiguration] = None):
                 is used to obtain the configuration.
 
         Raises:
-            ApiException: if unable to communicate with the Alarm Service.
+            ApiException: if unable to communicate with the `/nialarm` Service.
         """
         if configuration is None:
             configuration = core.HttpConfigurationManager.get_configuration()
+
         super().__init__(configuration, base_path="/nialarm/v1/")
 
-    @post("acknowledge-instances-by-instance-id")
-    def acknowledge_instances_by_instance_id(
-        self, request: models.AcknowledgeByInstanceIdRequest
+    @post(
+        "acknowledge-instances-by-instance-id",
+        args=[Field("instanceIds"), Field("forceClear")],
+    )
+    def acknowledge_alarm(
+        self, instance_ids: list[str], force_clear: bool = False
     ) -> models.AcknowledgeByInstanceIdResponse:
         """Acknowledges one or more alarm instances by their instance IDs.
 
         Args:
-            request: The request containing instance IDs to acknowledge and optional force clear flag.
+            instance_ids: List of instance IDs (unique occurrence identifiers) of the alarms to acknowledge.
+                         These are the server-generated IDs returned when creating/updating alarms,
+                         not the user-defined alarm_id.
+            force_clear: Whether or not the affected alarms should have their clear field set to true.
+                         Defaults to False.
 
         Returns:
             A response containing the instance IDs that were successfully acknowledged,
             the instance IDs that failed, and error details for failures.
 
         Raises:
-            ApiException: if unable to communicate with the Alarm Service or provided invalid arguments.
+            ApiException: if unable to communicate with the `/nialarm` Service or provided invalid arguments.
         """
         ...
 
-    @post("instances")
-    def create_or_update_alarm(
-        self, request: models.CreateOrUpdateAlarmRequest
-    ) -> models.CreateOrUpdateAlarmResponse:
+    @post("instances", return_key="instanceId")
+    def create_or_update_alarm(self, request: models.CreateOrUpdateAlarmRequest) -> str:
         """Creates or updates an instance, or occurrence, of an alarm.
 
         Creates or updates an alarm based on the requested transition and the state
-        of the current active alarm with the given alarmId.
+        of the current active alarm with the given alarm_id (specified in the request).
+        Multiple calls with the same alarm_id will update the same alarm instance.
 
         Args:
-            request: The request containing alarm information and transition details.
+            request: The request containing alarm_id (user-defined identifier),
+                    transition details, and other alarm properties.
 
         Returns:
-            A response containing the ID of the created or modified alarm.
+            The instance_id (unique occurrence identifier) of the created or modified alarm.
+            Use this ID for operations like get_alarm(), delete_alarm(), or acknowledge.
 
         Raises:
-            ApiException: if unable to communicate with the Alarm Service or provided invalid arguments.
+            ApiException: if unable to communicate with the `/nialarm` Service or provided invalid arguments.
         """
         ...
 
     @get("instances/{instance_id}")
     def get_alarm(self, instance_id: str) -> models.Alarm:
-        """Gets an alarm by its instanceId.
+        """Gets an alarm by its instance_id.
 
         Args:
-            instance_id: Unique ID of a particular instance, or occurrence, of an alarm.
+            instance_id: The unique instance ID (occurrence identifier) of the alarm to retrieve.
+                        This is the server-generated ID returned from create_or_update_alarm(),
+                        not the user-defined alarm_id.
 
         Returns:
-            The alarm with the specified instance ID.
+            The alarm with the specified instance_id.
 
         Raises:
-            ApiException: if unable to communicate with the Alarm Service or provided invalid arguments.
+            ApiException: if unable to communicate with the `/nialarm` Service or provided invalid arguments.
         """
         ...
 
     @delete("instances/{instance_id}")
     def delete_alarm(self, instance_id: str) -> None:
-        """Deletes an alarm by its instanceId.
+        """Deletes an alarm by its instance_id.
 
         Args:
-            instance_id: Unique ID of a particular instance, or occurrence, of an alarm.
+            instance_id: The unique instance ID (occurrence identifier) of the alarm to delete.
+                        This is the server-generated ID returned from create_or_update_alarm(),
+                        not the user-defined alarm_id.
 
         Raises:
-            ApiException: if unable to communicate with the Alarm Service or provided invalid arguments.
+            ApiException: if unable to communicate with the `/nialarm` Service or provided invalid arguments.
         """
         ...
 
-    @post("delete-instances-by-instance-id")
+    @post("delete-instances-by-instance-id", args=[Field("instanceIds")])
     def delete_instances_by_instance_id(
-        self, request: models.DeleteByInstanceIdRequest
+        self, instance_ids: list[str]
     ) -> models.DeleteByInstanceIdResponse:
-        """Deletes multiple alarm instances by their instanceIds.
+        """Deletes multiple alarm instances by their instance IDs.
 
         Args:
-            request: Contains the instanceIds of the alarms to delete.
+            instance_ids: List of instance IDs (unique occurrence identifiers) of the alarms to delete.
+                         These are the server-generated IDs returned when creating/updating alarms,
+                         not the user-defined alarm_id.
 
         Returns:
-            A response containing lists of successfully deleted and failed instanceIds,
+            A response containing lists of successfully deleted and failed instance IDs,
             along with error information for failures.
 
         Raises:
-            ApiException: if unable to communicate with the Alarm Service or provided invalid arguments.
+            ApiException: if unable to communicate with the `/nialarm` Service or provided invalid arguments.
         """
         ...
 
@@ -131,6 +147,6 @@ def query_alarms(
             optional total count and continuation token for pagination.
 
         Raises:
-            ApiException: if unable to communicate with the Alarm Service or provided invalid arguments.
+            ApiException: if unable to communicate with the `/nialarm` Service or provided invalid arguments.
         """
         ...

nisystemlink/clients/alarm/models/__init__.py

@@ -1,11 +1,15 @@
-from ._acknowledge_by_instance_id_request import AcknowledgeByInstanceIdRequest
 from ._acknowledge_by_instance_id_response import AcknowledgeByInstanceIdResponse
-from ._alarm import Alarm
-from ._create_or_update_alarm_request import CreateOrUpdateAlarmRequest
-from ._create_or_update_alarm_response import CreateOrUpdateAlarmResponse
-from ._delete_by_instance_id_request import DeleteByInstanceIdRequest
+from ._alarm import Alarm, AlarmNote, AlarmTransition, AlarmTransitionType
+from ._create_or_update_alarm_request import (
+    CreateAlarmTransition,
+    CreateOrUpdateAlarmRequest,
+)
 from ._delete_by_instance_id_response import DeleteByInstanceIdResponse
-from ._query_alarms_request import QueryWithFilterRequest
+from ._query_alarms_request import (
+    AlarmOrderBy,
+    QueryWithFilterRequest,
+    TransitionInclusionOption,
+)
 from ._query_alarms_response import QueryWithFilterResponse
 
 # flake8: noqa

nisystemlink/clients/alarm/models/_acknowledge_by_instance_id_request.py

@@ -1,12 +1,12 @@
 from typing import List
 
 from nisystemlink.clients.alarm.models._partial_success_response_base import (
-    PartialSuccessResponseBase,
+    AlarmInstancesPartialSuccess,
 )
 
 
-class AcknowledgeByInstanceIdResponse(PartialSuccessResponseBase):
+class AcknowledgeByInstanceIdResponse(AlarmInstancesPartialSuccess):
     """Contains information about which alarms were acknowledged."""
 
     acknowledged: List[str]
-    """The instanceIds of the alarms which were successfully acknowledged."""
+    """The instanceIds of the alarms that were successfully acknowledged."""

nisystemlink/clients/alarm/models/_acknowledge_by_instance_id_response.py

@@ -1,12 +1,12 @@
 from typing import List
 
 from nisystemlink.clients.alarm.models._partial_success_response_base import (
-    PartialSuccessResponseBase,
+    AlarmInstancesPartialSuccess,
 )
 
 
-class DeleteByInstanceIdResponse(PartialSuccessResponseBase):
-    """Contains information about which alarms were deleted."""
+class DeleteByInstanceIdResponse(AlarmInstancesPartialSuccess):
+    """Contains information about alarms that were deleted."""
 
     deleted: List[str]
     """The instanceIds of the alarms that were successfully deleted."""