diff --git a/src/DataMiner/SLManagedAutomation/Engine.cs b/src/DataMiner/SLManagedAutomation/Engine.cs index 425054a288..91ff4ee000 100644 --- a/src/DataMiner/SLManagedAutomation/Engine.cs +++ b/src/DataMiner/SLManagedAutomation/Engine.cs @@ -5,6 +5,7 @@ using Skyline.DataMiner.Net.Exceptions; using Skyline.DataMiner.Net.Profiles; using System.Collections.Generic; +using Skyline.DataMiner.Net.Messages.SLDataGateway; namespace Skyline.DataMiner.Automation { @@ -165,31 +166,51 @@ public Engine() { } /// /// Acknowledges the specified alarm tree using the provided comment message. /// - /// The DataMiner Agent ID. - /// The alarm ID. + /// The alarm tree to update /// A comment. /// If a user launches the script manually or attaches to it interactively, that user will become the owner of the alarm. If the script runs in the background, the alarm owner will become “Administrator”. /// /// - /// engine.AcknowledgeAlarm(7, 304022, "Alarm acknowledged."); + /// engine.AcknowledgeAlarm(new AlarmTreeID(7, 400, 304022), "Alarm acknowledged."); /// /// - public void AcknowledgeAlarm(int dataMinerID, int alarmID, string comment) { } + public void AcknowledgeAlarm(AlarmTreeID alarmTreeID, string comment) { } - /// - /// Acknowledges the specified alarm tree using the provided comment message. - /// - /// The DataMiner Agent ID. - /// The element ID. - /// The alarm ID. - /// A comment. - /// If a user launches the script manually or attaches to it interactively, that user will become the owner of the alarm. If the script runs in the background, the alarm owner will become “Administrator”. - /// - /// - /// engine.AcknowledgeAlarm(7, 400, 304022, "Alarm acknowledged."); - /// - /// - public void AcknowledgeAlarm(int dataMinerID, int elementID, int alarmID, string comment) { } + /// + /// Acknowledges the specified alarm tree using the provided comment message. + /// + /// The DataMiner Agent ID. + /// The alarm ID. + /// A comment. + /// + /// If a user launches the script manually or attaches to it interactively, that user will become the owner of the alarm. If the script runs in the background, the alarm owner will become “Administrator”. + /// Although this method is obsolete, it will still work on a DMS without Swarming enabled until 10.6. + /// + /// + /// + /// engine.AcknowledgeAlarm(7, 304022, "Alarm acknowledged."); + /// + /// + [Obsolete("Please use the overload that takes an AlarmTreeID (still supported in <= 10.6 on non-swarming systems)")] + public void AcknowledgeAlarm(int dataMinerID, int alarmID, string comment) { } + + /// + /// Acknowledges the specified alarm tree using the provided comment message. + /// + /// The DataMiner Agent ID. + /// The element ID. + /// The alarm ID. + /// A comment. + /// + /// If a user launches the script manually or attaches to it interactively, that user will become the owner of the alarm. If the script runs in the background, the alarm owner will become “Administrator”. + /// For performance reasons, we recommend using the overload that takes an AlarmTreeID instead. + /// + /// + /// + /// engine.AcknowledgeAlarm(7, 400, 304022, "Alarm acknowledged."); + /// + /// + public void AcknowledgeAlarm(int dataMinerID, int elementID, int alarmID, string comment) { } /// /// Adds an error message to the Automation script, which will eventually cause the script to fail. @@ -797,36 +818,53 @@ public void ExitSuccess(string reason) { } /// public void GenerateInformation(string text) { } - /// - /// Retrieves the value of the specified custom alarm property. - /// - /// The DataMiner Agent ID. - /// The alarm ID. - /// The name of the alarm property. - /// Alarm not found. - /// The value of the specified alarm property. - /// - /// - /// string propertyValue = engine.GetAlarmProperty(200, 59851, "SourceDetail"); - /// - /// - public string GetAlarmProperty(int dataMinerID, int alarmID, string propertyName) { return null; } + /// + /// Retrieves the value of the specified custom alarm property. + /// + /// The alarm ID + /// The name of the alarm property. + /// Alarm not found. + /// The value of the specified alarm property. + /// + /// + /// string propertyValue = engine.GetAlarmProperty(new AlarmID(new AlarmTreeID(200, 400, 59851), 59853), "SourceDetail"); + /// + /// + public string GetAlarmProperty(AlarmID alarmID, string propertyName) { return null; } - /// - /// Retrieves the value of the specified custom alarm property. - /// - /// The DataMiner Agent ID. - /// The element ID. - /// The alarm ID. - /// The name of the alarm property. - /// Alarm not found. - /// The value of the specified alarm property. - /// - /// - /// string propertyValue = engine.GetAlarmProperty(200, 400, 59851, "SourceDetail"); - /// - /// - public string GetAlarmProperty(int dataMinerID, int elementID, int alarmID, string propertyName) { return null; } + /// + /// Retrieves the value of the specified custom alarm property. + /// + /// The DataMiner Agent ID. + /// The alarm ID. + /// The name of the alarm property. + /// Alarm not found. + /// The value of the specified alarm property. + /// Although this method is obsolete, it will still work on a DMS without Swarming enabled until 10.6. + /// + /// + /// string propertyValue = engine.GetAlarmProperty(200, 59851, "SourceDetail"); + /// + /// + [Obsolete("Please use the overload that takes an AlarmID object (still supported in <= 10.6 on non-swarming systems)")] + public string GetAlarmProperty(int dataMinerID, int alarmID, string propertyName) { return null; } + + /// + /// Retrieves the value of the specified custom alarm property. + /// + /// The DataMiner Agent ID. + /// The element ID. + /// The alarm ID. + /// The name of the alarm property. + /// Alarm not found. + /// The value of the specified alarm property. + /// For performance reasons, we recommend using the overload that takes an AlarmID instead. + /// + /// + /// string propertyValue = engine.GetAlarmProperty(200, 400, 59851, "SourceDetail"); + /// + /// + public string GetAlarmProperty(int dataMinerID, int elementID, int alarmID, string propertyName) { return null; } /// /// Retrieves an object representing one of the script dummies. @@ -1350,88 +1388,135 @@ public void SendSms(string message, string to) { } /// /// Sets the specified custom alarm properties to the specified values. /// - /// The DataMiner Agent ID. - /// The alarm ID. + /// The alarm tree to update. /// The names of the properties. /// The values of the properties. /// /// /// - /// Feature introduced in DataMiner 8.5.2 (RN 8347). /// In DataMiner versions prior to 9.0, this method cannot be used to override alarm property values that are defined in the element protocol. - /// When an alarm property value has been defined in the element protocol and this method is used to explicitly assign a new value to the property, the new value will only be retained until the severity of the alarm changes. After this, the value from the protocol is used again. + /// When an alarm property value has been defined in the element protocol, and this method is used to explicitly assign a new value to the property, the new value will only be retained until the severity of the alarm changes. After this, the value from the protocol is used again. /// /// /// /// /// - /// engine.SetAlarmProperties(200, 521655, new string[]{"Property A", "Property B"}, new string[]{"Value A", "Value B"}); + /// engine.SetAlarmProperties(new AlarmTreeID(200, 400, 521655), new string[]{"Property A", "Property B"}, new string[]{"Value A", "Value B"}); /// /// - public void SetAlarmProperties(int dataMinerID, int alarmID, string[] propertyNames, string[] propertyValues) { } + public void SetAlarmProperties(AlarmTreeID alarmTreeID, string[] propertyNames, string[] propertyValues) { } - /// - /// Sets the specified custom alarm properties to the specified values. - /// - /// The DataMiner Agent ID. - /// The element ID. - /// The alarm ID. - /// The names of the properties. - /// The values of the properties. - /// - /// - /// - /// In DataMiner versions prior to 9.0, this method cannot be used to override alarm property values that are defined in the element protocol. - /// When an alarm property value has been defined in the element protocol and this method is used to explicitly assign a new value to the property, the new value will only be retained until the severity of the alarm changes. After this, the value from the protocol is used again. - /// - /// - /// - /// - /// - /// engine.SetAlarmProperties(200, 400, 521655, new string[]{"Property A", "Property B"}, new string[]{"Value A", "Value B"}); - /// - /// - public void SetAlarmProperties(int dataMinerID, int elementID, int alarmID, string[] propertyNames, string[] propertyValues) { } + /// + /// Sets the specified custom alarm properties to the specified values. + /// + /// The DataMiner Agent ID. + /// The alarm ID. + /// The names of the properties. + /// The values of the properties. + /// + /// + /// + /// Feature introduced in DataMiner 8.5.2 (RN 8347). + /// In DataMiner versions prior to 9.0, this method cannot be used to override alarm property values that are defined in the element protocol. + /// When an alarm property value has been defined in the element protocol, and this method is used to explicitly assign a new value to the property, the new value will only be retained until the severity of the alarm changes. After this, the value from the protocol is used again. + /// Although this method is obsolete, it will still work on a DMS without Swarming enabled until 10.6. + /// + /// + /// + /// + /// + /// engine.SetAlarmProperties(200, 521655, new string[]{"Property A", "Property B"}, new string[]{"Value A", "Value B"}); + /// + /// + [Obsolete("Please use the overload that takes an AlarmTreeID (still supported in <= 10.6 on non-swarming systems)")] + public void SetAlarmProperties(int dataMinerID, int alarmID, string[] propertyNames, string[] propertyValues) { } - /// - /// Updates a custom alarm property. - /// - /// The DataMiner Agent ID. - /// The alarm ID. - /// The property name. - /// The value to set. - /// - /// - /// - /// In DataMiner versions prior to 9.0, this method cannot be used to override alarm property values that are defined in the element protocol. - /// When an alarm property value has been defined in the element protocol and this method is used to explicitly assign a new value to the property, the new value will only be retained until the severity of the alarm changes. After this, the value from the protocol is used again. - /// - /// - /// - /// - /// - /// engine.SetAlarmProperty(200, 521655, "Property A", "Value A"); - /// - /// - public void SetAlarmProperty(int dataMinerID, int alarmID, string propertyName, string propertyValue) { } + /// + /// Sets the specified custom alarm properties to the specified values. + /// + /// The DataMiner Agent ID. + /// The element ID. + /// The alarm ID. + /// The names of the properties. + /// The values of the properties. + /// + /// + /// + /// In DataMiner versions prior to 9.0, this method cannot be used to override alarm property values that are defined in the element protocol. + /// When an alarm property value has been defined in the element protocol, and this method is used to explicitly assign a new value to the property, the new value will only be retained until the severity of the alarm changes. After this, the value from the protocol is used again. + /// For performance reasons, we recommend using the overload that takes an AlarmTreeID instead. + /// + /// + /// + /// + /// + /// engine.SetAlarmProperties(200, 400, 521655, new string[]{"Property A", "Property B"}, new string[]{"Value A", "Value B"}); + /// + /// + public void SetAlarmProperties(int dataMinerID, int elementID, int alarmID, string[] propertyNames, string[] propertyValues) { } - /// - /// Updates a custom alarm property. - /// - /// The DataMiner Agent ID. - /// The element ID. - /// The alarm ID. - /// The name of the property. - /// The value to set. - /// - /// - /// - /// In DataMiner versions prior to 9.0, this method cannot be used to override alarm property values that are defined in the element protocol. - /// When an alarm property value has been defined in the element protocol and this method is used to explicitly assign a new value to the property, the new value will only be retained until the severity of the alarm changes. After this, the value from the protocol is used again. - /// - /// - /// - public void SetAlarmProperty(int dataMinerID, int elementID, int alarmID, string propertyName, string propertyValue) { } + /// + /// Updates a custom alarm property. + /// + /// The alarm tree to update. + /// The property name. + /// The value to set. + /// + /// + /// + /// When an alarm property value has been defined in the element protocol, and this method is used to explicitly assign a new value to the property, the new value will only be retained until the severity of the alarm changes. After this, the value from the protocol is used again. + /// + /// + /// + /// + /// + /// engine.SetAlarmProperty(new AlarmTreeID(200, 456, 521655), "Property A", "Value A"); + /// + /// + public void SetAlarmProperty(AlarmTreeID alarmTreeID, string propertyName, string propertyValue) { } + + /// + /// Updates a custom alarm property. + /// + /// The DataMiner Agent ID. + /// The alarm ID. + /// The property name. + /// The value to set. + /// + /// + /// + /// In DataMiner versions prior to 9.0, this method cannot be used to override alarm property values that are defined in the element protocol. + /// When an alarm property value has been defined in the element protocol, and this method is used to explicitly assign a new value to the property, the new value will only be retained until the severity of the alarm changes. After this, the value from the protocol is used again. + /// Although this method is obsolete, it will still work on a DMS without Swarming enabled until 10.6. + /// + /// + /// + /// + /// + /// engine.SetAlarmProperty(200, 521655, "Property A", "Value A"); + /// + /// + [Obsolete("Please use the overload that takes an AlarmTreeID (still supported in <= 10.6 on non-swarming systems)")] + public void SetAlarmProperty(int dataMinerID, int alarmID, string propertyName, string propertyValue) { } + + /// + /// Updates a custom alarm property. + /// + /// The DataMiner Agent ID. + /// The element ID. + /// The alarm ID. + /// The name of the property. + /// The value to set. + /// + /// + /// + /// In DataMiner versions prior to 9.0, this method cannot be used to override alarm property values that are defined in the element protocol. + /// When an alarm property value has been defined in the element protocol, and this method is used to explicitly assign a new value to the property, the new value will only be retained until the severity of the alarm changes. After this, the value from the protocol is used again. + /// For performance reasons, we recommend using the overload that takes an AlarmTreeID instead. + /// + /// + /// + public void SetAlarmProperty(int dataMinerID, int elementID, int alarmID, string propertyName, string propertyValue) { } /// /// Allows setting at runtime. diff --git a/src/DataMiner/SLManagedAutomation/IEngine.cs b/src/DataMiner/SLManagedAutomation/IEngine.cs index 6b9ca3d762..4e1018fbe6 100644 --- a/src/DataMiner/SLManagedAutomation/IEngine.cs +++ b/src/DataMiner/SLManagedAutomation/IEngine.cs @@ -1,6 +1,7 @@ using Skyline.DataMiner.Net; using Skyline.DataMiner.Net.Exceptions; using Skyline.DataMiner.Net.Messages; +using Skyline.DataMiner.Net.Messages.SLDataGateway; using Skyline.DataMiner.Net.Profiles; using System; using System.Collections.Generic; @@ -13,34 +14,54 @@ namespace Skyline.DataMiner.Automation /// public interface IEngine { - /// - /// Acknowledges the specified alarm tree using the provided comment message. - /// - /// The DataMiner Agent ID. - /// The alarm ID. - /// A comment. - /// If a user launches the script manually or attaches to it interactively, that user will become the owner of the alarm. If the script runs in the background, the alarm owner will become “Administrator”. - /// - /// - /// engine.AcknowledgeAlarm(7, 304022, "Alarm acknowledged."); - /// - /// + /// + /// Acknowledges the specified alarm tree using the provided comment message. + /// + /// The alarm tree to update + /// A comment. + /// If a user launches the script manually or attaches to it interactively, that user will become the owner of the alarm. If the script runs in the background, the alarm owner will become “Administrator”. + /// + /// + /// engine.AcknowledgeAlarm(new AlarmTreeID(7, 400, 304022), "Alarm acknowledged."); + /// + /// + void AcknowledgeAlarm(AlarmTreeID alarmTreeID, string comment); + + /// + /// Acknowledges the specified alarm tree using the provided comment message. + /// + /// The DataMiner Agent ID. + /// The alarm ID. + /// A comment. + /// + /// If a user launches the script manually or attaches to it interactively, that user will become the owner of the alarm. If the script runs in the background, the alarm owner will become “Administrator”. + /// Although this method is obsolete, it will still work on a DMS without Swarming enabled until 10.6. + /// + /// + /// + /// engine.AcknowledgeAlarm(7, 304022, "Alarm acknowledged."); + /// + /// + [Obsolete("Please use the overload that takes an AlarmTreeID (still supported in <= 10.6 on non-swarming systems)")] void AcknowledgeAlarm(int dataMinerID, int alarmID, string comment); - /// - /// Acknowledges the specified alarm tree using the provided comment message. - /// - /// The DataMiner Agent ID. - /// The element ID. - /// The alarm ID. - /// A comment. - /// If a user launches the script manually or attaches to it interactively, that user will become the owner of the alarm. If the script runs in the background, the alarm owner will become “Administrator”. - /// - /// - /// engine.AcknowledgeAlarm(7, 400, 304022, "Alarm acknowledged."); - /// - /// - void AcknowledgeAlarm(int dataMinerID, int elementID, int alarmID, string comment); + /// + /// Acknowledges the specified alarm tree using the provided comment message. + /// + /// The DataMiner Agent ID. + /// The element ID. + /// The alarm ID. + /// A comment. + /// + /// If a user launches the script manually or attaches to it interactively, that user will become the owner of the alarm. If the script runs in the background, the alarm owner will become “Administrator”. + /// For performance reasons, we recommend using the overload that takes an AlarmTreeID instead. + /// + /// + /// + /// engine.AcknowledgeAlarm(7, 400, 304022, "Alarm acknowledged."); + /// + /// + void AcknowledgeAlarm(int dataMinerID, int elementID, int alarmID, string comment); /// /// Adds an error message to the Automation script, which will eventually cause the script to fail. @@ -611,49 +632,66 @@ public interface IEngine /// ScriptDummy GetDummy(string name); - /// - /// Retrieves the value of the specified custom alarm property. - /// - /// The DataMiner Agent ID. - /// The element ID. - /// The alarm ID. - /// The name of the alarm property. - /// Alarm not found. - /// The value of the specified alarm property. - /// - /// - /// string propertyValue = engine.GetAlarmProperty(200, 400, 59851, "SourceDetail"); - /// - /// - string GetAlarmProperty(int dataMinerID, int elementID, int alarmID, string propertyName); - - /// - /// Retrieves the value of the specified custom alarm property. - /// - /// The DataMiner Agent ID. - /// The alarm ID. - /// The name of the alarm property. - /// Alarm not found. - /// The value of the specified alarm property. - /// - /// - /// string propertyValue = engine.GetAlarmProperty(200, 59851, "SourceDetail"); - /// - /// + /// + /// Retrieves the value of the specified custom alarm property. + /// + /// The alarm ID + /// The name of the alarm property. + /// Alarm not found. + /// The value of the specified alarm property. + /// + /// + /// string propertyValue = engine.GetAlarmProperty(new AlarmID(new AlarmTreeID(200, 400, 59851), 59853), "SourceDetail"); + /// + /// + string GetAlarmProperty(AlarmID alarmID, string propertyName); + + /// + /// Retrieves the value of the specified custom alarm property. + /// + /// The DataMiner Agent ID. + /// The element ID. + /// The alarm ID. + /// The name of the alarm property. + /// Alarm not found. + /// The value of the specified alarm property. + /// For performance reasons, we recommend using the overload that takes an AlarmID instead. + /// + /// + /// string propertyValue = engine.GetAlarmProperty(200, 400, 59851, "SourceDetail"); + /// + /// + string GetAlarmProperty(int dataMinerID, int elementID, int alarmID, string propertyName); + + /// + /// Retrieves the value of the specified custom alarm property. + /// + /// The DataMiner Agent ID. + /// The alarm ID. + /// The name of the alarm property. + /// Alarm not found. + /// The value of the specified alarm property. + /// Although this method is obsolete, it will still work on a DMS without Swarming enabled until 10.6. + /// + /// + /// string propertyValue = engine.GetAlarmProperty(200, 59851, "SourceDetail"); + /// + /// + [Obsolete("Please use the overload that takes an AlarmID object (still supported in <= 10.6 on non-swarming systems)")] string GetAlarmProperty(int dataMinerID, int alarmID, string propertyName); - /// - /// Retrieves an object representing one of the script dummies. - /// - /// The dummy ID. - /// The object representing the specified script dummy or if the dummy with the specified ID is not found. - /// Through this object, actions like "set parameter" can be executed. - /// - /// - /// ScriptDummy dummyTest = engine.GetDummy(5); - /// - /// - ScriptDummy GetDummy(int id); + /// + /// Retrieves an object representing one of the script dummies. + /// + /// The dummy ID. + /// The object representing the specified script dummy or if the dummy with the specified ID is not found. + /// Through this object, actions like "set parameter" can be executed. + /// + /// + /// ScriptDummy dummyTest = engine.GetDummy(5); + /// + /// + ScriptDummy GetDummy(int id); /// /// Retrieves an object representing one of the script’s memory files. Through this object, data can be read from or written into the memory file. @@ -960,89 +998,130 @@ public interface IEngine /// void SaveValue(string name, string value); - /// - /// Updates a custom alarm property. - /// - /// The DataMiner Agent ID. - /// The element ID. - /// The alarm ID. - /// The name of the property. - /// The value to set. - /// - /// - /// - /// In DataMiner versions prior to 9.0, this method cannot be used to override alarm property values that are defined in the element protocol. - /// When an alarm property value has been defined in the element protocol and this method is used to explicitly assign a new value to the property, the new value will only be retained until the severity of the alarm changes. After this, the value from the protocol is used again. - /// - /// - /// - void SetAlarmProperty(int dataMinerID, int elementID, int alarmID, string propertyName, string propertyValue); - - /// - /// Updates a custom alarm property. - /// - /// The DataMiner Agent ID. - /// The alarm ID. - /// The property name. - /// The value to set. - /// - /// - /// - /// In DataMiner versions prior to 9.0, this method cannot be used to override alarm property values that are defined in the element protocol. - /// When an alarm property value has been defined in the element protocol and this method is used to explicitly assign a new value to the property, the new value will only be retained until the severity of the alarm changes. After this, the value from the protocol is used again. - /// - /// - /// - /// - /// - /// engine.SetAlarmProperty(200, 521655, "Property A", "Value A"); - /// - /// + /// + /// Updates a custom alarm property. + /// + /// The alarm tree to update. + /// The name of the property. + /// The value to set. + /// + /// + /// + /// When an alarm property value has been defined in the element protocol, and this method is used to explicitly assign a new value to the property, the new value will only be retained until the severity of the alarm changes. After this, the value from the protocol is used again. + /// + /// + /// + void SetAlarmProperty(AlarmTreeID alarmTreeID, string propertyName, string propertyValue); + + /// + /// Updates a custom alarm property. + /// + /// The DataMiner Agent ID. + /// The element ID. + /// The alarm ID. + /// The name of the property. + /// The value to set. + /// + /// + /// + /// In DataMiner versions prior to 9.0, this method cannot be used to override alarm property values that are defined in the element protocol. + /// When an alarm property value has been defined in the element protocol, and this method is used to explicitly assign a new value to the property, the new value will only be retained until the severity of the alarm changes. After this, the value from the protocol is used again. + /// For performance reasons, we recommend using the overload that takes an AlarmTreeID instead. + /// + /// + /// + void SetAlarmProperty(int dataMinerID, int elementID, int alarmID, string propertyName, string propertyValue); + + /// + /// Updates a custom alarm property. + /// + /// The DataMiner Agent ID. + /// The alarm ID. + /// The property name. + /// The value to set. + /// + /// + /// + /// In DataMiner versions prior to 9.0, this method cannot be used to override alarm property values that are defined in the element protocol. + /// When an alarm property value has been defined in the element protocol, and this method is used to explicitly assign a new value to the property, the new value will only be retained until the severity of the alarm changes. After this, the value from the protocol is used again. + /// Although this method is obsolete, it will still work on a DMS without Swarming enabled until 10.6. + /// + /// + /// + /// + /// + /// engine.SetAlarmProperty(200, 521655, "Property A", "Value A"); + /// + /// + [Obsolete("Please use the overload that takes an AlarmTreeID (still supported in <= 10.6 on non-swarming systems)")] void SetAlarmProperty(int dataMinerID, int alarmID, string propertyName, string propertyValue); - /// - /// Sets the specified custom alarm properties to the specified values. - /// - /// The DataMiner Agent ID. - /// The element ID. - /// The alarm ID. - /// The names of the properties. - /// The values of the properties. - /// - /// - /// - /// In DataMiner versions prior to 9.0, this method cannot be used to override alarm property values that are defined in the element protocol. - /// When an alarm property value has been defined in the element protocol and this method is used to explicitly assign a new value to the property, the new value will only be retained until the severity of the alarm changes. After this, the value from the protocol is used again. - /// - /// - /// - /// - /// - /// engine.SetAlarmProperties(200, 400, 521655, new string[]{"Property A", "Property B"}, new string[]{"Value A", "Value B"}); - /// - /// + /// + /// Sets the specified custom alarm properties to the specified values. + /// + /// The alarm tree to update. + /// The names of the properties. + /// The values of the properties. + /// + /// + /// + /// When an alarm property value has been defined in the element protocol, and this method is used to explicitly assign a new value to the property, the new value will only be retained until the severity of the alarm changes. After this, the value from the protocol is used again. + /// + /// + /// + /// + /// + /// engine.SetAlarmProperties(new AlarmTreeID(200, 400, 521655), new string[]{"Property A", "Property B"}, new string[]{"Value A", "Value B"}); + /// + /// + void SetAlarmProperties(AlarmTreeID alarmTreeID, string[] propertyNames, string[] propertyValues); + + /// + /// Sets the specified custom alarm properties to the specified values. + /// + /// The DataMiner Agent ID. + /// The element ID. + /// The alarm ID. + /// The names of the properties. + /// The values of the properties. + /// + /// + /// + /// In DataMiner versions prior to 9.0, this method cannot be used to override alarm property values that are defined in the element protocol. + /// When an alarm property value has been defined in the element protocol, and this method is used to explicitly assign a new value to the property, the new value will only be retained until the severity of the alarm changes. After this, the value from the protocol is used again. + /// For performance reasons, we recommend using the overload that takes an AlarmTreeID instead. + /// + /// + /// + /// + /// + /// engine.SetAlarmProperties(200, 400, 521655, new string[]{"Property A", "Property B"}, new string[]{"Value A", "Value B"}); + /// + /// void SetAlarmProperties(int dataMinerID, int elementID, int alarmID, string[] propertyNames, string[] propertyValues); - /// - /// Sets the specified custom alarm properties to the specified values. - /// - /// The DataMiner Agent ID. - /// The alarm ID. - /// The names of the properties. - /// The values of the properties. - /// - /// - /// - /// In DataMiner versions prior to 9.0, this method cannot be used to override alarm property values that are defined in the element protocol. - /// When an alarm property value has been defined in the element protocol and this method is used to explicitly assign a new value to the property, the new value will only be retained until the severity of the alarm changes. After this, the value from the protocol is used again. - /// - /// - /// - /// - /// - /// engine.SetAlarmProperties(200, 521655, new string[]{"Property A", "Property B"}, new string[]{"Value A", "Value B"}); - /// - /// + /// + /// Sets the specified custom alarm properties to the specified values. + /// + /// The DataMiner Agent ID. + /// The alarm ID. + /// The names of the properties. + /// The values of the properties. + /// + /// + /// + /// In DataMiner versions prior to 9.0, this method cannot be used to override alarm property values that are defined in the element protocol. + /// When an alarm property value has been defined in the element protocol, and this method is used to explicitly assign a new value to the property, the new value will only be retained until the severity of the alarm changes. After this, the value from the protocol is used again. + /// Although this method is obsolete, it will still work on a DMS without Swarming enabled until 10.6. + /// + /// + /// + /// + /// + /// engine.SetAlarmProperties(200, 521655, new string[]{"Property A", "Property B"}, new string[]{"Value A", "Value B"}); + /// + /// + [Obsolete("Please use the overload that takes an AlarmTreeID (still supported in <= 10.6 on non-swarming systems)")] void SetAlarmProperties(int dataMinerID, int alarmID, string[] propertyNames, string[] propertyValues); diff --git a/src/DataMiner/SLNetTypes/Info/IDObjects/AlarmID.cs b/src/DataMiner/SLNetTypes/Info/IDObjects/AlarmID.cs index 914e5a1ce5..e8fbae9511 100644 --- a/src/DataMiner/SLNetTypes/Info/IDObjects/AlarmID.cs +++ b/src/DataMiner/SLNetTypes/Info/IDObjects/AlarmID.cs @@ -6,7 +6,43 @@ namespace Skyline.DataMiner.Net.Messages.SLDataGateway { + [Serializable] public class AlarmID //: DMAObjectRef, DataTypeID, IMaskable, IEquatable, IComparable, IComparable - { - } + { + /// + /// The tree of this alarm event + /// + public AlarmTreeID TreeID { get; set; } + + /// + /// The alarm ID of this event in the tree + /// + public int EventID { get; set; } + + /// + /// Is this the root event in the tree + /// + public bool IsTreeRoot => TreeID.RootAlarmID == EventID; + + /// + /// Builds an AlarmID reference for a given tree ID and event ID within that tree + /// + public AlarmID(AlarmTreeID tree, int eventId) + { + TreeID = tree; + EventID = eventId; + } + + /// + /// Builds an AlarmID reference for a specific alarm event + /// + public AlarmID(AlarmEventMessage alarmEvent) + { + } + + [Obsolete("Use version which takes AlarmTreeID (still supported in <= 10.6)")] + public AlarmID(int dataMinerId, long alarmId, long rootId) + { + } + } } diff --git a/src/DataMiner/SLNetTypes/Info/IDObjects/AlarmTreeID.cs b/src/DataMiner/SLNetTypes/Info/IDObjects/AlarmTreeID.cs new file mode 100644 index 0000000000..1a9f7ad69a --- /dev/null +++ b/src/DataMiner/SLNetTypes/Info/IDObjects/AlarmTreeID.cs @@ -0,0 +1,43 @@ +using Skyline.DataMiner.Net.Messages; +using Skyline.DataMiner.Net.Messages.SLDataGateway; +using System; + +namespace Skyline.DataMiner.Net +{ + /// + /// Represents a reference to one specific alarm tree. + /// + [Serializable] + public sealed class AlarmTreeID //: DMAObjectRef, IEquatable + { + // Default constructor is required for protobuf. + public AlarmTreeID() { } + + /// + /// Element on which the alarm tree lives or lived. + /// Guaranteed non-null. + /// + public ElementID ElementID { get; } + + /// + /// Identifier for the alarm tree. Guaranteed to be unique within the element context. + /// Always positive. + /// + public int RootAlarmID { get; } + + public AlarmTreeID(ElementID elementId, int rootAlarmId) + { + + } + + public AlarmTreeID(AlarmEventMessage alarm) + { + } + + public AlarmTreeID(AlarmTreeID other) + { + } + + public AlarmTreeID(int dmaid, int eid, int rootAlarmId) : this(new ElementID(dmaid, eid), rootAlarmId) { } + } +}