feat:AlarmApiClient

Author: RSam-NI

nisystemlink/clients/alarm/_alarm_client.py

@@ -0,0 +1,136 @@
+"""Implementation of Alarm Client"""
+
+from typing import Optional
+
+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 Path, retry
+
+from . import models
+
+
+@retry(
+    when=retry.when.status(408, 429, 502, 503, 504),
+    stop=retry.stop.after_attempt(5),
+    on_exception=retry.CONNECTION_ERROR,
+)
+class AlarmClient(BaseClient):
+    def __init__(self, configuration: Optional[core.HttpConfiguration] = None):
+        """Initialize an instance.
+
+        Args:
+            configuration: Defines the web server to connect to and information about
+                how to connect. If not provided, the
+                :class:`HttpConfigurationManager <nisystemlink.clients.core.HttpConfigurationManager>`
+                is used to obtain the configuration.
+
+        Raises:
+            ApiException: if unable to communicate with the Alarm 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
+    ) -> 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.
+
+        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.
+        """
+        ...
+
+    @post("instances")
+    def create_or_update_alarm(
+        self, request: models.CreateOrUpdateAlarmRequest
+    ) -> models.CreateOrUpdateAlarmResponse:
+        """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.
+
+        Args:
+            request: The request containing alarm information and transition details.
+
+        Returns:
+            A response containing the ID of the created or modified alarm.
+
+        Raises:
+            ApiException: if unable to communicate with the Alarm Service or provided invalid arguments.
+        """
+        ...
+
+    @get("instances/{instance_id}")
+    def get_alarm(self, instance_id: str) -> models.Alarm:
+        """Gets an alarm by its instanceId.
+
+        Args:
+            instance_id: Unique ID of a particular instance, or occurrence, of an alarm.
+
+        Returns:
+            The alarm with the specified instance ID.
+
+        Raises:
+            ApiException: if unable to communicate with the Alarm Service or provided invalid arguments.
+        """
+        ...
+
+    @delete("instances/{instance_id}")
+    def delete_alarm(self, instance_id: str) -> None:
+        """Deletes an alarm by its instanceId.
+
+        Args:
+            instance_id: Unique ID of a particular instance, or occurrence, of an alarm.
+
+        Raises:
+            ApiException: if unable to communicate with the Alarm Service or provided invalid arguments.
+        """
+        ...
+
+    @post("delete-instances-by-instance-id")
+    def delete_instances_by_instance_id(
+        self, request: models.DeleteByInstanceIdRequest
+    ) -> models.DeleteByInstanceIdResponse:
+        """Deletes multiple alarm instances by their instanceIds.
+
+        Args:
+            request: Contains the instanceIds of the alarms to delete.
+
+        Returns:
+            A response containing lists of successfully deleted and failed instanceIds,
+            along with error information for failures.
+
+        Raises:
+            ApiException: if unable to communicate with the Alarm Service or provided invalid arguments.
+        """
+        ...
+
+    @post("query-instances-with-filter")
+    def query_alarms(
+        self, request: models.QueryWithFilterRequest
+    ) -> models.QueryWithFilterResponse:
+        """Queries for instances, or occurrences, of alarms using Dynamic LINQ.
+
+        Specifying an empty JSON object in the request body will result in all alarms being returned.
+
+        Args:
+            request: The request containing filter information and query options.
+
+        Returns:
+            A response containing the list of alarms that match the query, along with 
+            optional total count and continuation token for pagination.
+
+        Raises:
+            ApiException: if unable to communicate with the Alarm Service or provided invalid arguments.
+        """
+        ...

nisystemlink/clients/alarm/models/__init__.py

@@ -0,0 +1,11 @@
+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 ._delete_by_instance_id_response import DeleteByInstanceIdResponse
+from ._query_alarms_request import QueryWithFilterRequest
+from ._query_alarms_response import QueryWithFilterResponse
+
+# flake8: noqa

nisystemlink/clients/alarm/models/_acknowledge_by_instance_id_request.py

@@ -0,0 +1,13 @@
+from typing import List, Optional
+
+from nisystemlink.clients.core._uplink._json_model import JsonModel
+
+
+class AcknowledgeByInstanceIdRequest(JsonModel):
+    """Contains information about the alarms to acknowledge."""
+
+    instance_ids: List[str]
+    """The instanceIds of the alarms which should be acknowledged."""
+
+    force_clear: Optional[bool] = False
+    """Whether or not the affected alarms should have their clear field set to true."""

nisystemlink/clients/alarm/models/_acknowledge_by_instance_id_response.py

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

nisystemlink/clients/alarm/models/_alarm.py

@@ -0,0 +1,219 @@
+from datetime import datetime
+from enum import Enum
+from typing import Dict, List, Optional
+
+from nisystemlink.clients.core._uplink._json_model import JsonModel
+
+
+class AlarmTransitionType(str, Enum):
+    """Specifies a type of alarm transition."""
+
+    CLEAR = "CLEAR"
+    """The transition corresponds to the clearing of the condition tracked by the alarm."""
+
+    SET = "SET"
+    """The transition corresponds to the condition tracked by the alarm entering into the triggered state."""
+
+
+class AlarmTransition(JsonModel):
+    """A transition within an instance, or occurrence, of an alarm.
+    
+    Alarm transitions record changes to an alarm's clear field as well as an alarm 
+    increasing or decreasing in severity.
+    """
+
+    transition_type: AlarmTransitionType
+    """Specifies a type of alarm transition: CLEAR or SET."""
+
+    occurred_at: datetime
+    """The date and time when the transition occurred."""
+
+    severity_level: int
+    """The severity of the transition.
+    
+    Valid values for CLEAR transitions are [-1, -1]. 
+    Valid values for SET transitions are [1, infinity].
+    Note that the SystemLink Alarm UI only has display strings for SET severities in the range [1, 4].
+    """
+
+    value: str
+    """The value that caused the alarm to transition."""
+
+    condition: str
+    """A description of the condition associated with the transition."""
+
+    short_text: str
+    """A short description of the condition."""
+
+    detail_text: str
+    """A detailed description of the condition."""
+
+    keywords: List[str]
+    """Words or phrases associated with a transition.
+    
+    Useful for attaching metadata to a transition which could aid in an investigation 
+    into an alarm's root cause in the future.
+    """
+
+    properties: Dict[str, str]
+    """Key-value pair metadata associated with a transition.
+    
+    Useful for attaching additional metadata to a transition which could aid in an investigation 
+    into an alarm's root cause in the future. Property keys must be between 1 and 255 characters.
+    """
+
+
+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.
+    
+    The lifecycle of an alarm begins the first time it is triggered and ends when it has been 
+    both acknowledged and cleared. The service enforces the invariant that there can be at most 
+    one active=True alarm with the same alarmId.
+    """
+
+    instance_id: str
+    """The unique identifier for the instance, or occurrence, of the alarm."""
+
+    alarm_id: str
+    """A value meant to uniquely identify the particular process or condition tracked by the alarm.
+    
+    For example, alarms created by a tag rule engine might have their alarmIds set to the 
+    concatenation of the path of the tag which caused the rule to be triggered and the ID of the rule.
+    """
+
+    workspace: str
+    """The workspace the alarm belongs to."""
+
+    active: bool
+    """Whether or not the alarm is active.
+    
+    An active alarm deserves human or automated attention. Alarms always begin life with active=True. 
+    This field will be automatically set to false when the clear and acknowledged fields are set to true.
+    """
+
+    clear: bool
+    """When set to true, the condition that triggered the alarm no longer matches the trigger condition.
+    
+    When an alarm is created, clear is initially set to false. The creator of the alarm (typically a 
+    rule engine or application element of some sort) may determine that the trigger condition no longer 
+    applies, and may send an update, clearing the alarm. Clearing the alarm does not deactivate the alarm, 
+    unless the alarm had previously been acknowledged. As long as the alarm is active=true, the alarm may 
+    transition from clear=True to clear=False (or vice versa) multiple times.
+    """
+
+    acknowledged: bool
+    """When set to true, the alarm has been acknowledged by an alarm handler, which is typically a human.
+    
+    Alarms always begin life with acknowledged=False. Acknowledging an alarm will not affect the active 
+    flag unless clear is also true. When clear and acknowledged are true, the alarm will become inactive 
+    (active=False). This field is automatically reset to false when the alarm's highestSeverityLevel field increases.
+    """
+
+    acknowledged_at: Optional[datetime]
+    """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]
+    """The userId of the individual who acknowledged the alarm.
+    
+    This field will be cleared when the alarm's highestSeverityLevel field increases.
+    """
+
+    occurred_at: datetime
+    """The date and time when the alarm was created/first occurred."""
+
+    updated_at: datetime
+    """The date and time when the alarm was last updated or modified."""
+
+    created_by: str
+    """An identifier for who or what created the alarm.
+    
+    This is usually used to identify the particular rule engine which requested that the alarm be created.
+    """
+
+    transitions: List[AlarmTransition]
+    """A collection of AlarmTransitions for the alarm.
+    
+    The service stores the first transition and the most recent 99 other transitions by default. 
+    The configuration for the service determines the total number of stored transitions per alarm.
+    """
+
+    transition_overflow_count: int
+    """The number of transitions which overflowed the transitions field for the alarm.
+    
+    For example, if the alarm transitioned 250 times, transitionOverflowCount is set to 150 and 
+    transitions contains the first and most recent 99 transitions. The configuration for the service 
+    determines the total number of stored transitions per alarm.
+    """
+
+    notification_strategy_ids: List[str]
+    """The IDs of the notification strategies which will be triggered.
+    
+    These are triggered when the alarm is first created and when its highestSeverityLevel increases.
+    """
+
+    current_severity_level: int
+    """The current severity level of the alarm."""
+
+    highest_severity_level: int
+    """The highest severity level that the alarm has ever been in."""
+
+    most_recent_set_occurred_at: Optional[datetime]
+    """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]
+    """The date and time of the most recent occurrence of a transition.
+    
+    This property only considers transitions that cause an alarm state change.
+    """
+
+    channel: str
+    """An identifier for the tag or resource associated with the alarm."""
+
+    condition: str
+    """A description of the condition associated with the alarm."""
+
+    display_name: str
+    """Optional display name for the alarm. Display names do not need to be unique."""
+
+    description: str
+    """Optional description text for the alarm."""
+
+    keywords: List[str]
+    """Words or phrases associated with the alarm.
+    
+    Alarms can be tagged with keywords to make it easier to find them with queries.
+    """
+
+    notes: List[AlarmNote]
+    """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.
+    """
+
+    properties: Dict[str, str]
+    """The alarm's custom properties."""
+
+    resource_type: str
+    """The type of resource associated with the alarm."""