fix:PRComments

Author: RSam-NI

examples/alarm/alarm.py

@@ -4,18 +4,18 @@
 from nisystemlink.clients.alarm import AlarmClient
 from nisystemlink.clients.alarm.models import (
     AlarmOrderBy,
-    AlarmTransitionType,
-    CreateAlarmTransition,
+    AlarmSeverityLevel,
+    ClearAlarmTransition,
     CreateOrUpdateAlarmRequest,
     QueryAlarmsWithFilterRequest,
-    TransitionInclusionOption,
+    SetAlarmTransition,
 )
 from nisystemlink.clients.core import HttpConfiguration
 
 # Setup the server configuration to point to your instance of SystemLink Enterprise
 server_configuration = HttpConfiguration(
-    server_uri="https://yourserver.yourcompany.com",
-    api_key="YourAPIKeyGeneratedFromSystemLink",
+    server_uri="https://test-api.lifecyclesolutions.ni.com/",
+    api_key="oVu4EpiijnlgwjPlY58lke8H1xv2XLuCo1QmAvveMI",
 )
 client = AlarmClient(configuration=server_configuration)
 
@@ -26,10 +26,9 @@
 # Create an alarm with a SET transition
 create_request = CreateOrUpdateAlarmRequest(
     alarm_id=alarm_id,
-    transition=CreateAlarmTransition(
-        transition_type=AlarmTransitionType.SET,
+    transition=SetAlarmTransition(
         occurred_at=datetime.now(),
-        severity_level=3,
+        severity_level=AlarmSeverityLevel.HIGH,
         condition="Temperature exceeded threshold",
         message="Temperature sensor reading: 85°C",
     ),
@@ -39,14 +38,14 @@
 
 # Get the alarm by its instance ID (the unique occurrence identifier)
 alarm = client.get_alarm(id)
+print(f"Retrieved alarm: {alarm.alarm_id}, Condition: {alarm.condition}")
 
 # Update the alarm with a higher severity (same alarm_id, updates the same instance)
 update_request = CreateOrUpdateAlarmRequest(
     alarm_id=alarm_id,
-    transition=CreateAlarmTransition(
-        transition_type=AlarmTransitionType.SET,
+    transition=SetAlarmTransition(
         occurred_at=datetime.now(),
-        severity_level=5,
+        severity_level=AlarmSeverityLevel.CRITICAL,
         condition="Temperature critically high",
         message="Temperature sensor reading: 95°C",
     ),
@@ -55,25 +54,21 @@
 
 # Query alarms with a filter (can filter by alarm_id to find all instances)
 query_request = QueryAlarmsWithFilterRequest(
-    filter=f'alarmId="{alarm_id}"',
-    transition_inclusion_option=TransitionInclusionOption.ALL,
+    filter="alarmId=@0",
+    substitutions=[alarm_id],
     order_by=AlarmOrderBy.UPDATED_AT,
     order_by_descending=True,
-    return_count=True,
 )
 query_response = client.query_alarms(query_request)
 
-# Acknowledge all queried alarms
-queried_alarm_ids = [alarm.instance_id for alarm in query_response.alarms]
-ack_response = client.acknowledge_alarms(ids=queried_alarm_ids)
+# Acknowledge the alarm
+client.acknowledge_alarms(ids=[id])
 
 # Clear the alarm
 clear_request = CreateOrUpdateAlarmRequest(
     alarm_id=alarm_id,
-    transition=CreateAlarmTransition(
-        transition_type=AlarmTransitionType.CLEAR,
+    transition=ClearAlarmTransition(
         occurred_at=datetime.now(),
-        severity_level=0,
         condition="Temperature returned to normal",
     ),
 )

nisystemlink/clients/alarm/_alarm_client.py

@@ -1,6 +1,6 @@
 """Implementation of Alarm Client"""
 
-from typing import List, Optional
+from typing import List
 
 from nisystemlink.clients import core
 from nisystemlink.clients.core._uplink._base_client import BaseClient
@@ -17,7 +17,7 @@
 )
 class AlarmClient(BaseClient):
 
-    def __init__(self, configuration: Optional[core.HttpConfiguration] = None):
+    def __init__(self, configuration: core.HttpConfiguration | None = None):
         """Initialize an instance.
 
         Args:
@@ -39,7 +39,7 @@ def __init__(self, configuration: Optional[core.HttpConfiguration] = None):
         args=[Field("instanceIds"), Field("forceClear")],
     )
     def acknowledge_alarms(
-        self, ids: List[str], force_clear: bool = False
+        self, ids: List[str], *, force_clear: bool = False
     ) -> models.AcknowledgeAlarmsResponse:
         """Acknowledges one or more alarm instances by their instance IDs.
 
@@ -77,6 +77,9 @@ def create_or_update_alarm(self, request: models.CreateOrUpdateAlarmRequest) ->
 
         Raises:
             ApiException: if unable to communicate with the `/nialarm` Service or provided invalid arguments.
+                A 409 Conflict error occurs when the request does not represent a valid transition
+                for an existing alarm, such as attempting to clear an alarm which is already clear,
+                or attempting to set an alarm which is already set at the given severity level.
         """
         ...
 

nisystemlink/clients/alarm/models/__init__.py

@@ -1,8 +1,10 @@
 from ._acknowledge_alarms_response import AcknowledgeAlarmsResponse
-from ._alarm import Alarm, AlarmNote, AlarmTransition, AlarmTransitionType
+from ._alarm import Alarm, AlarmSeverityLevel, AlarmTransition, AlarmTransitionType
 from ._create_or_update_alarm_request import (
+    ClearAlarmTransition,
     CreateAlarmTransition,
     CreateOrUpdateAlarmRequest,
+    SetAlarmTransition,
 )
 from ._delete_alarms_response import DeleteAlarmsResponse
 from ._query_alarms_request import (

nisystemlink/clients/alarm/models/_alarm.py

@@ -1,10 +1,33 @@
 from datetime import datetime
-from enum import Enum
-from typing import Dict, List, Optional
+from enum import Enum, IntEnum
+from typing import Any, Dict, List
 
 from nisystemlink.clients.core._uplink._json_model import JsonModel
 
 
+class AlarmSeverityLevel(IntEnum):
+    """Well-known alarm severity levels.
+
+    The service supports custom severity levels greater than 4, but it is generally discouraged.
+    The SystemLink Alarm UI only has display strings for severity levels in the range [1, 4].
+    """
+
+    CLEAR = -1
+    """Indicates an alarm clearance."""
+
+    LOW = 1
+    """Low severity level."""
+
+    MODERATE = 2
+    """Moderate severity level."""
+
+    HIGH = 3
+    """High severity level."""
+
+    CRITICAL = 4
+    """Critical severity level."""
+
+
 class AlarmTransitionType(str, Enum):
     """Specifies a type of alarm transition."""
 
@@ -32,7 +55,7 @@ class AlarmTransition(JsonModel):
     """The severity of the transition.
 
     Valid values for CLEAR transitions are [-1, -1].
-    Valid values for SET transitions are [1, infinity].
+    Valid values for SET transitions are [1, 2147483647].
     Note that the SystemLink Alarm UI only has display strings for SET severities in the range [1, 4].
     """
 
@@ -63,22 +86,6 @@ class AlarmTransition(JsonModel):
     """
 
 
-class AlarmNote(JsonModel):
-    """Information about a particular alarm instance.
-
-    Such as a description of the root cause of the alarm.
-    """
-
-    note: str
-    """Information about a particular alarm instance, such as a description of the root cause of the alarm."""
-
-    created_at: Optional[datetime] = None
-    """The date and time when the note was created."""
-
-    user: Optional[str] = None
-    """The userId of the person who created the note."""
-
-
 class Alarm(JsonModel):
     """An individual instance, or occurrence, of an alarm.
 
@@ -125,13 +132,13 @@ class Alarm(JsonModel):
     (active=False). This field is automatically reset to false when the alarm's highestSeverityLevel field increases.
     """
 
-    acknowledged_at: Optional[datetime]
+    acknowledged_at: datetime | None
     """The date and time when the alarm instance was acknowledged.
 
     This field will be cleared when the alarm's highestSeverityLevel field increases.
     """
 
-    acknowledged_by: Optional[str]
+    acknowledged_by: str | None
     """The userId of the individual who acknowledged the alarm.
 
     This field will be cleared when the alarm's highestSeverityLevel field increases.
@@ -176,13 +183,13 @@ class Alarm(JsonModel):
     highest_severity_level: int
     """The highest severity level that the alarm has ever been in."""
 
-    most_recent_set_occurred_at: Optional[datetime]
+    most_recent_set_occurred_at: datetime | None
     """The date and time of the most recent occurrence of a SET transition.
 
     This property only considers transitions that cause an alarm state change.
     """
 
-    most_recent_transition_occurred_at: Optional[datetime]
+    most_recent_transition_occurred_at: datetime | None
     """The date and time of the most recent occurrence of a transition.
 
     This property only considers transitions that cause an alarm state change.
@@ -206,10 +213,10 @@ class Alarm(JsonModel):
     Alarms can be tagged with keywords to make it easier to find them with queries.
     """
 
-    notes: List[AlarmNote]
+    notes: List[Any]
     """A collection of notes for a given alarm instance.
 
-    Notes are set by humans to record information such as the root cause of the alarm.
+    Notes are not currently supported and this will always be an empty list.
     """
 
     properties: Dict[str, str]

nisystemlink/clients/alarm/models/_alarm_instances_partial_success.py

@@ -1,4 +1,4 @@
-from typing import List, Optional
+from typing import List
 
 from nisystemlink.clients.core import ApiError
 from nisystemlink.clients.core._uplink._json_model import JsonModel
@@ -10,5 +10,5 @@ class AlarmInstancesPartialSuccess(JsonModel):
     failed: List[str]
     """The instanceIds that failed the operation."""
 
-    error: Optional[ApiError] = None
+    error: ApiError | None = None
     """The error that occurred during the operation."""