applied updates

Author: PedroDebevere

develop/part6Ttools/TOOProtocolDevelopmentWithCICD/Pipeline_stages_for_functions.md

@@ -14,6 +14,10 @@ Currently, the pipeline for function development consists of the following steps
 
     See [Declarative checkout from SCM](#declarative-checkout-from-scm).
 
+- Validate tag
+
+    See [Validate tag](#validate-tag).
+
 - (Release) Prepare for SVN
 
     See [(Release) Prepare for SVN](#release-prepare-for-svn).
@@ -32,6 +36,15 @@ When a new Git repository is created using the SLC SE Repository Manager tool, t
 
 In this step, Jenkins loads the current repository from Git.
 
+## Validate tag
+
+This step is only executed for pipeline runs for a tag. It will verify whether the specified tag meets the following conditions:
+
+- The tag has the correct format.
+- The tag is in the expected branch. For example, a tag "1.0.0.1" provided on a commit that is part of the "1.0.0.X" branch will succeed, while a tag "1.0.0.1" provided on a commit belonging to branch 1.0.1.x will fail.
+- All expected previous minor versions of the tag are present. For example, if a commit has been tagged with "1.0.0.4", the tags "1.0.0.1", "1.0.0.2" and "1.0.0.3" are expected to be present already.
+- The tag is an annotated tag and not a lightweight tag.
+
 ## (Release) Prepare for SVN
 
 In case a tag was detected and the version should therefore be pushed to SVN, some preparatory steps are performed.

filterConfig.yml

@@ -1,4 +1,7 @@
 apiRules:
+- include:
+    uiRegex: ^Skyline\.DataMiner\.Net\.AutomationUI\.Objects
+    type: Namespace
 - exclude:
     uidRegex: ^Tamir\.SharpSsh\.jsch\.ChannelSftp$
     type: Type
@@ -161,9 +164,6 @@ apiRules:
 - exclude:
     uidRegex: ^Skyline\.DataMiner\.Net\.Messages\.AutomationCheckType$
     type: Type
-- exclude:
-    uidRegex: ^Skyline\.DataMiner\.Net\.Messages\.AutomationScriptAttachOptions$
-    type: Type
 - exclude:
     uidRegex: ^Skyline\.DataMiner\.Net\.Messages\.DMSMessage$
     type: Type
@@ -227,9 +227,6 @@ apiRules:
 - exclude:
     uidRegex: ^Skyline\.DataMiner\.Net\.Messages\.PropertyInfo.DataTypes$
     type: Type
-- exclude:
-    uidRegex: ^Skyline\.DataMiner\.Net\.Messages\.RedundancyMode$
-    type: Type
 - exclude:
     uidRegex: ^Skyline\.DataMiner\.Net\.Messages\.SLDataGateway\.AlarmID$
     type: Type

src/DataMiner/SLManagedAutomation/Element.cs

@@ -90,6 +90,11 @@ public class Element : IActionableElement
 		/// Gets the name of the element.
 		/// </summary>
 		/// <value>The name of the element.</value>
+		/// <remarks>
+		/// <note type="note">
+		/// <para>This property returns the following string: "_&lt;agentID&gt;_&lt;elementID&gt; (e.g. "_100_5612"). To retrieve the element name, use the <see cref="Element.ElementName"/> property.</para>
+		/// </note>
+		/// </remarks>
 		/// <example>
 		/// <code>
 		/// Element element = engine.FindElement(400, 2000);
@@ -2945,10 +2950,9 @@ public virtual void MatrixStopBeingMaster(int pid, int master) { }
 		public virtual void Pause() { }
 
 		/// <summary>
-		/// Removes the link between this element and the alarm template that is assigned to it.
+		/// Removes the link between this element and the alarm template that is assigned to it. This sets the element to “Not Monitored”.
 		/// </summary>
 		/// <example>
-		/// <remarks>In other words, set the element to “Not Monitored”.</remarks>
 		/// <code>
 		/// Element element = engine.FindElement(400, 2000);
 		/// element.RemoveAlarmTemplate();
@@ -2957,9 +2961,8 @@ public virtual void Pause() { }
 		public virtual void RemoveAlarmTemplate() { }
 
 		/// <summary>
-		/// Removes the link between an element and the trend template that is assigned to it.
+		/// Removes the link between an element and the trend template that is assigned to it. This disables trending for the element.
 		/// </summary>
-		/// <remarks>In other words, dis­able trending for the element.</remarks>
 		/// <example>
 		/// <code>
 		/// Element element = engine.FindElement(400, 2000);
@@ -3100,19 +3103,19 @@ public virtual void SetParameterByPrimaryKey(int pid, string primaryKey, object
         /// </code>
         /// </example>
         /// <remarks>
-        /// <para>Since DataMiner 10.0.5 (RN 25025, RN 25195), this method will only return after having checked that the property was set correctly.</para>
+        /// <para>From DataMiner 10.0.5 (RN 25025, RN 25195) onwards, this method will only return after having checked that the property was set correctly.</para>
         /// <para>Prior to DataMiner 10.0.5, when the value of an element property was updated using the SetPropertyValue method on an Element object and immediately retrieved using the GetPropertyValue method, in some cases, the value returned by that last method would incorrectly be the previous value.</para>
         /// <note type="note">
         /// <para>The SetPropertyValue method will only perform the above-mentioned check when the “check sets” option is enabled.</para>
         /// <list type="bullet">
         /// <item>
-        /// <description>Before launching a script in Cube, select the “After executing a SET command, check if the read parameter or property has been set to the new value” check box in the script execution window.</description>
+        /// <description>Before launching a script in Cube, select the “After executing a SET command, check if the read parameter or property has been set to the new value” checkbox in the script execution window.</description>
         /// </item>
         /// <item>
         /// <description>When launching a script using ExecuteScriptMessage, make sure to activate the CHECKSETS option(“CHECKSETS:TRUE”).</description>
         /// </item>
         /// </list>
-        /// <para>With this option enabled, the SetPropertyValue method will take slightly longer to execute.When a large number of properties need to be updated which do not need to be retrieved immediately, you can disable this option in order to increase performance.</para>
+        /// <para>With this option enabled, the SetPropertyValue method will take slightly longer to execute. When a large number of properties need to be updated that do not need to be retrieved immediately, you can disable this option in order to increase performance.</para>
         /// </note>
         /// </remarks>
         public virtual void SetPropertyValue(string propertyName, string propertyValue) { }
@@ -3183,41 +3186,77 @@ public virtual void SpectrumEnableMonitor(string monitorName) { }
 		/// </summary>
 		/// <param name="measurementPointName">The name of the measurement point.</param>
 		/// <returns>The ID that corresponds with the specified spectrum measurement point name or -1 when not found.</returns>
+		/// <example>
+		/// <code>
+		/// var element = engine.FindElement("MySpectrumElement");
+		/// int measurementPointId = element.SpectrumFindMeasurementPointIdByName("MyMeasurement PointName");
+		/// </code>
+		/// </example>
 		public virtual int SpectrumFindMeasurementPointIdByName(string measurementPointName) { return 0; }
 
 		/// <summary>
 		/// Gets the ID that corresponds with the specified spectrum monitor name.
 		/// </summary>
 		/// <param name="monitorName">The spectrum monitor name.</param>
 		/// <returns>The ID that corresponds with the specified spectrum monitor name or -1 when not found.</returns>
+		/// <example>
+		/// <code>
+		/// var element = engine.FindElement("MySpectrumElement ");
+		/// int monitorId = element.SpectrumFindMonitorIdByName("MyMonitorName");
+		/// </code>
+		/// </example>
 		public virtual int SpectrumFindMonitorIdByName(string monitorName) { return 0; }
 
 		/// <summary>
 		/// Returns a value indicating whether the specified spectrum monitor is enabled.
 		/// </summary>
 		/// <param name="monitorName">The name of the spectrum monitor.</param>
 		/// <returns><c>true</c> if the specified spectrum monitor is enabled; otherwise, <c>false</c>.</returns>
+		/// <example>
+		/// <code>
+		/// var element = engine.FindElement("MySpectrumElement");
+		/// bool isEnabled = element.SpectrumIsMonitorEnabled("MyMonitorName ");
+		/// </code>
+		/// </example>
 		public virtual bool SpectrumIsMonitorEnabled(string monitorName) { return false; }
 
 		/// <summary>
 		/// Returns a value indicating whether the specified spectrum monitor is enabled.
 		/// </summary>
 		/// <param name="monitorId">The ID of the spectrum monitor.</param>
 		/// <returns><c>true</c> if the specified spectrum monitor is enabled; otherwise, <c>false</c>.</returns>
+		/// <example>
+		/// <code>
+		/// var element = engine.FindElement(10);
+		/// bool isEnabled = element.SpectrumIsMonitorEnabled("MyMonitorName ");
+		/// </code>
+		/// </example>
 		public virtual bool SpectrumIsMonitorEnabled(int monitorId) { return false; }
 
 		/// <summary>
 		/// Selects the measurement point(s) on which a spectrum monitor has to be executed.
 		/// </summary>
 		/// <param name="monitorName">The name of the spectrum monitor.</param>
 		/// <param name="measurementPointNames">The names of the measurement points.</param>
+		/// <example>
+		/// <code>
+		/// var element = engine.FindElement("MySpectrumElement ");
+		/// element.SpectrumSelectMeasurementPointsForMonitor("MyMonitorName ", new string[]{"MyMeasurementPoint"});
+		/// </code>
+		/// </example>
 		public virtual void SpectrumSelectMeasurementPointsForMonitor(string monitorName, params string[] measurementPointNames) { }
 
 		/// <summary>
 		/// Selects the measurement point(s) on which a spectrum monitor has to be executed.
 		/// </summary>
 		/// <param name="monitorId">The ID of the spectrum monitor.</param>
 		/// <param name="measurementPointIds">The IDs of the measurement points.</param>
+		/// <example>
+		/// <code>
+		/// var element = engine.FindElement("MySpectrumElement ");
+		/// element.SpectrumSelectMeasurementPointsForMonitor("MyMonitorName ", new int[]{1, 2});
+		/// </code>
+		/// </example>
 		public virtual void SpectrumSelectMeasurementPointsForMonitor(int monitorId, params int[] measurementPointIds) { }
 
 		/// <summary>

src/DataMiner/SLManagedAutomation/EmailOptions.cs

@@ -33,15 +33,15 @@ public EmailOptions(string message, string title, string to) : base((Notificatio
 		}
 
 		/// <summary>
-		/// Gets or sets the blank carbon copy (bcc) recipients.
+		/// Gets or sets the blank carbon copy (BCC) recipients.
 		/// </summary>
-		/// <value>The blank carbon copy (bcc) recipients.</value>
+		/// <value>The blank carbon copy (BCC) recipients.</value>
 		public string BCC { get; set; }
 
 		/// <summary>
-		/// Gets or sets the carbon copy (cc) recipients.
+		/// Gets or sets the carbon copy (CC) recipients.
 		/// </summary>
-		/// <value>The carbon copy (cc) recipients.</value>
+		/// <value>The carbon copy (CC) recipients.</value>
 		public string CC { get; set; }
 
 		/// <summary>

src/DataMiner/SLManagedAutomation/Engine.cs

@@ -30,7 +30,7 @@ public Engine() { }
         /// Gets the raw SLNet connection.
         /// </summary>
         /// <value>The raw SLNet connection.</value>
-        /// <remarks>It is advised to used the <see cref="SendSLNetMessage(DMSMessage)"/> or <see cref="SendSLNetSingleResponseMessage(DMSMessage)"/> method instead of the raw connection to send messages (as the method on the raw connection does not encapsulate the messages with an impersonate message.). Since DataMiner 10.0.1, to send multiple messages, the <see cref="SendSLNetMessages(DMSMessage[])"/> method can be used.</remarks>
+        /// <remarks>It is advised to used the <see cref="SendSLNetMessage(DMSMessage)"/> or <see cref="SendSLNetSingleResponseMessage(DMSMessage)"/> method instead of the raw connection to send messages (as the method on the raw connection does not encapsulate the messages with an impersonate message.). From DataMiner 10.0.1 onwards, to send multiple messages, the <see cref="SendSLNetMessages(DMSMessage[])"/> method can be used.</remarks>
         public static Connection SLNetRaw { get; }
 
 		/// <summary>
@@ -114,6 +114,11 @@ public Engine() { }
 		/// Gets or sets the timeout for the current C# code block.
 		/// </summary>
 		/// <value>The timeout for the current C# code block.</value>
+		/// <remarks>
+		/// <note type="note">
+		/// <para>From DataMiner 10.2.0/10.1.2 onwards, this property can also be used to determine when an interactive Automation script times out.</para>
+		/// </note>
+		/// </remarks>
 		/// <example>
 		/// <code>
 		/// var timeout = engine.Timeout;
@@ -210,7 +215,7 @@ public virtual void AddScriptOutput(string key, string value) { }
 		/// <param name="key">The key to add or update.</param>
 		/// <param name="value">The value.</param>
 		/// <remarks>
-		/// <para>If the key already exists, it will update it with the specified value.</para>
+		/// <para>If the key already exists, it will be updated with the specified value.</para>
 		/// <para>Feature introduced in DataMiner 10.0.2 (RN 23936).</para>
 		/// </remarks>
 		public virtual void AddOrUpdateScriptOutput(string key, string value)
@@ -497,8 +502,8 @@ public void ExitSuccess(string reason) { }
 		/// <item><description>If the user clicks Attach, the script will start in a pop-up window.</description></item>
 		/// <item><description>If the user clicks Ignore, the message box will be closed.</description></item>
 		/// </list>
-		/// <note type="note">In DataMiner Cube, you can also use the script action Find interactive client, instead of using C#. For more information, see Find interactive client.</note>
-		/// <para>Since DataMiner 9.6.9 (RN 22227), it is possible to find an interactive client by user cookie instead of by user name.</para>
+		/// <note type="note">In DataMiner Cube, you can also use the script action Find interactive client, instead of using C#. For more information, see <see href="xref:AutomationActionFindInteractiveClient">Find interactive client</see>.</note>
+		/// <para>From DataMiner 9.6.9 (RN 22227) onwards, it is possible to find an interactive client by user cookie instead of by user name.</para>
 		/// <code>bool ok = engine.FindInteractiveClient("Some text", 100, "userCookie:" + connection.ConnectionID);</code>
 		/// </remarks>
 		/// <example>
@@ -536,7 +541,7 @@ public void ExitSuccess(string reason) { }
 		/// <item><description>If the user clicks Ignore, the message box will be closed.</description></item>
 		/// </list>
 		/// <note type="note">In DataMiner Cube, you can also use the script action Find interactive client, instead of using C#. For more information, see Find interactive client.</note>
-		/// <para>Since DataMiner 9.6.9 (RN 22227), it is possible to find an interactive client by user cookie instead of by user name.</para>
+		/// <para>From DataMiner 9.6.9 (RN 22227) onwards, it is possible to find an interactive client by user cookie instead of by user name.</para>
 		/// <code>bool ok = engine.FindInteractiveClient("Some text", 100, "userCookie:" + connection.ConnectionID, AutomationScriptAttachOptions.None);</code>
 		/// </remarks>
 		/// <example>

src/DataMiner/SLManagedAutomation/InteractiveUserDetachedException.cs

@@ -3,7 +3,7 @@
 namespace Skyline.DataMiner.Automation
 {
 	/// <summary>
-	/// The exception that is thrown when user-interaction is attempted on a script that has been detached from the client.
+	/// The exception that is thrown when user interaction is attempted on a script that has been detached from the client.
 	/// </summary>
 	public class InteractiveUserDetachedException : DataMinerException
 	{

src/DataMiner/SLManagedAutomation/MailReportOptions.cs

@@ -34,6 +34,20 @@ public void AddReservationProperties(params string[] @params) { }
 		/// <remarks>
 		/// <para>Allows including table cells.</para>
 		/// </remarks>
+		/// <example>
+		/// <para>For an example showing how to pass single-value parameters as well as table cells to a report, see below:</para>
+		/// <code>
+		/// Element dummy1 = engine.FindElement("My Element");
+		/// MailReportOptions reportOptions = engine.PrepareMailReport("Report Name");
+		/// // Add single-value parameter
+		/// reportOptions.IncludeElement(dummy1, new MailReportParameter(dummy1, "Total Processor Load");
+		/// // Add table cell
+		/// reportOptions.IncludeElement(dummy1, new MailReportParameter(dummy1, "Bandwidth", "Eth0");
+		/// </code>
+		/// <note type="note">
+		/// <para>In the example above, the index argument has to contain the display key. If necessary, use the FindDisplayKey method on the element or the dummy to retrieve that key. See <see cref="Element.FindDisplayKey(int, String)"/>.</para>
+		/// </note>
+		/// </example>
 		public void IncludeElement(IActionableElement dummy, params MailReportParameter[] @params) { }
 
 		/// <summary>

src/DataMiner/SLManagedAutomation/RedundancyGroup.cs

@@ -11,16 +11,19 @@ public class RedundancyGroup
 		/// <summary>
 		/// Gets the DataMiner Agent ID of this redundancy group.
 		/// </summary>
+		/// <value>The DataMiner Agent ID of this redundancy group.</value>
 		public int DmaId { get; }
 
 		/// <summary>
 		/// Gets the ID of this redundancy group.
 		/// </summary>
+		/// <value>The ID of this redundancy group.</value>
 		public int GroupId { get; }
 
 		/// <summary>
 		/// Gets or sets the current operating mode of the redundancy group.
 		/// </summary>
+		/// <value>The current operating mode of the redundancy group.</value>
 		/// <exception cref="ArgumentException">
 		/// The redundancy group was not found.<br />
 		/// -or-<br />
@@ -31,11 +34,13 @@ public class RedundancyGroup
 		/// <summary>
 		/// Gets the name of the redundancy group.
 		/// </summary>
+		/// <value>The name of the redundancy group.</value>
 		public string Name { get; }
 
 		/// <summary>
 		/// Gets the raw info of the redundancy group.
 		/// </summary>
+		/// <value>The raw info of the redundancy group.</value>
 		public LiteRedundancyGroupInfoEvent RawInfo { get; }
 
 		/// <summary>

src/DataMiner/SLManagedAutomation/SLTicketingGateway.cs

@@ -26,7 +26,7 @@ public virtual void Dispose()
 		/// <summary>
 		/// Retrieves the non-masked ticket field resolvers corresponding to one or more filters.
 		/// </summary>
-		/// <param name="filters">A collection of filters. Each filter will be processed separately and the results will be added to the final response.</param>
+		/// <param name="filters">A collection of filters. Each filter will be processed separately, and the results will be added to the final response.</param>
 		/// <returns> The requested <see cref="TicketFieldResolver"/> objects.</returns>
 		public virtual IEnumerable<TicketFieldResolver> GetTicketFieldResolvers(params TicketFieldResolver[] filters) { return null; }
 
@@ -58,15 +58,15 @@ public virtual void Dispose()
 		/// </summary>
 		/// <param name="error">String with notifications and/or errors that occurred.</param>
 		/// <param name="resolvers">The ticket field resolvers you wish to add or edit.</param>
-		/// <returns><c>true</c> when add/editing the ticket field resolver(s) was successful; otherwise, <c>false</c>.</returns>
+		/// <returns><c>true</c> when adding/editing the ticket field resolver(s) was successful; otherwise, <c>false</c>.</returns>
 		public virtual bool SetTicketFieldResolvers(out string error, ref TicketFieldResolver[] resolvers) { error = ""; return false; }
 
 		/// <summary>
 		/// Adds or edits multiple tickets.
 		/// </summary>
 		/// <param name="error">String with notifications and/or errors that occurred.</param>
 		/// <param name="tickets">The tickets you wish to add or edit.</param>
-		/// <returns><c>true</c> when add/editing the ticket(s) was successful; otherwise, <c>false</c>.</returns>
+		/// <returns><c>true</c> when adding/editing the ticket(s) was successful; otherwise, <c>false</c>.</returns>
 		public virtual bool SetTickets(out string error, ref Ticket[] tickets) { error = ""; return false; }
 
 		/// <summary>