|
| 1 | +--- |
| 2 | +uid: Swarming_Tutorial_Enable |
| 3 | +keywords: swarming, swarming tutorial |
| 4 | +--- |
| 5 | + |
| 6 | +# Enabling Swarming |
| 7 | + |
| 8 | +In this tutorial, you will learn how to enable [Swarming](xref:Swarming) in your DMS and swarm your first element. The tutorial makes use of an example Automation script to demonstrate how you need to adjust scripts to make sure you can enable Swarming. |
| 9 | + |
| 10 | +The content and screenshots for this tutorial have been created using DataMiner version 10.5.3. |
| 11 | + |
| 12 | +## Prerequisites |
| 13 | + |
| 14 | +For this tutorial, you will need a DataMiner System that meets the following requirements: |
| 15 | + |
| 16 | +- [Connected to dataminer.services](https://docs.dataminer.services/user-guide/Cloud_Platform/Connecting_to_cloud/Connecting_your_DataMiner_System_to_the_cloud.html). |
| 17 | +- Using DataMiner 10.5.1/10.6.0 [CU0] or higher. |
| 18 | +- Containing two or more Agents, but no Failover Agents. If you are using a single Agent, you can follow along, but you will not be able to do the last step (swarming an element). |
| 19 | +- Using [STaaS](xref:STaaS) or a [dedicated clustered storage](xref:Configuring_dedicated_clustered_storage) setup. |
| 20 | +- Without [data offloads](xref:Offload_database) configured. |
| 21 | +- The [*LegacyReportsAndDashboards* soft-launch option](xref:Overview_of_Soft_Launch_Options#legacyreportsanddashboards) is not enabled. |
| 22 | + |
| 23 | +Other prerequisites for Swarming will be addressed later in this tutorial. |
| 24 | + |
| 25 | +## Overview |
| 26 | + |
| 27 | +- [Step 1: Deploy the tutorial package from the Catalog](#step-1-deploy-the-tutorial-package-from-the-catalog) |
| 28 | +- [Step 2: Create a basic test element](#step-2-create-a-basic-test-element) |
| 29 | +- [Step 3: Create a DataMiner backup (optional)](#step-3-create-a-dataminer-backup-optional) |
| 30 | +- [Step 4: Enable Swarming](#step-4-enable-swarming) |
| 31 | +- [Step 5: Swarm your first element](#step-5-swarm-your-first-element) |
| 32 | + |
| 33 | +## Step 1: Deploy the tutorial package from the Catalog |
| 34 | + |
| 35 | +To deploy the package: |
| 36 | + |
| 37 | +1. Go to the [Tutorial - Getting started with Swarming](https://catalog.dataminer.services/details/b087dd80-8a62-4ef0-9321-76964ac4e039) package in the DataMiner Catalog. |
| 38 | + |
| 39 | +1. Deploy the latest version of the package on your DMA using the *Deploy* button. |
| 40 | + |
| 41 | +1. When the package has been deployed, open DataMiner Cube and check whether you can see the following scripts in the *Kata - Swarming* folder of the Automation module: |
| 42 | + |
| 43 | + - *Mask Critical Alarms*: This is a demo script to mask the critical alarms of an element. |
| 44 | + |
| 45 | + - *Enable Swarming*: This interactive Automation script takes you through the enabling procedure for Swarming. |
| 46 | + |
| 47 | +  |
| 48 | + |
| 49 | +## Step 2: Create a basic test element |
| 50 | + |
| 51 | +In this tutorial, you will swarm an element. To avoid impacting ongoing operations, start by adding a new test element. |
| 52 | + |
| 53 | +You can either [create a new basic test element](xref:Adding_elements) yourself or import a demo element, e.g. by deploying the [Satellite Earth Station Uplink](https://catalog.dataminer.services/details/c8adec4a-e7be-47a4-b7a4-e574e0381fe6) package. |
| 54 | + |
| 55 | +If you choose to create a new element yourself, you can select any protocol of your choice for it, except for a spectrum protocol or a DVE protocol, as these would not result in a swarmable element. |
| 56 | + |
| 57 | +## Step 3: Create a DataMiner backup (optional) |
| 58 | + |
| 59 | +Once you enable Swarming, the element configuration of the DMS will be moved from disk to database, which is a change that cannot easily be rolled back. This is why taking a backup of your DataMiner Agents before you enable Swarming is highly recommended. |
| 60 | + |
| 61 | +For detailed steps, refer to [Backing up a DataMiner Agent](xref:Backing_up_a_DataMiner_Agent). |
| 62 | + |
| 63 | +## Step 4: Enable Swarming |
| 64 | + |
| 65 | +Swarming has its own set of prerequisites. In this step, you will use a script from the deployed package to make sure these are met and then enable Swarming. |
| 66 | + |
| 67 | +1. In the Automation module in DataMiner Cube, select the *Enable Swarming* script and click the *Execute* button. |
| 68 | + |
| 69 | +  |
| 70 | + |
| 71 | +1. In the pop-up window, click *Execute now*. |
| 72 | + |
| 73 | + Information about the Swarming prerequisites will be displayed. |
| 74 | + |
| 75 | +1. Take a look at the mentioned static requirements. |
| 76 | + |
| 77 | + These are the DMS requirements that are more difficult to change, such as the database type or Failover configuration. Based on the prerequisites for this tutorial, all prerequisites should be met, except possibly the requirement for compatible enhanced services. |
| 78 | + |
| 79 | +  |
| 80 | + |
| 81 | +1. In case *No incompatible enhanced services* is *Not Ok*: |
| 82 | + |
| 83 | + 1. Check in the DataMiner Catalog if a more recent version of the enhanced service connectors is available and upgrade to the latest version if possible. |
| 84 | + |
| 85 | + 1. If upgrading to a more recent version is not possible, follow the instructions to [prepare enhanced service connectors for Swarming](xref:SwarmingPrepare#enhanced-service-connectors) |
| 86 | + |
| 87 | + 1. Run the *Enable Swarming* script again. |
| 88 | + |
| 89 | +1. Click the *Analyze* button to start checking the alarm ID usage. |
| 90 | + |
| 91 | + This button will only be available once all static requirements are met. It will analyze the use of the unique identifiers of alarms in scripting (Automation scripts and QActions), as this has been modified to support Swarming. (See [About the alarm ID changes](xref:SwarmingPrepare#about-the-alarm-id-changes).) |
| 92 | + |
| 93 | + This check can take up to several minutes, depending on the number of scripts and connectors in the system. |
| 94 | + |
| 95 | +  |
| 96 | + |
| 97 | + > [!NOTE] |
| 98 | + > It is not possible to scan dependencies (e.g. NuGets) with this script, so these may still contain outdated references. However, if this should be the case, running these scripts on a system where Swarming is enabled will throw a clear error message. |
| 99 | +
|
| 100 | +1. Take a look at the results of the analysis. |
| 101 | + |
| 102 | +  |
| 103 | + |
| 104 | + The *Mask Critical Alarms* script will be displayed as one of the problems that have been found. This script takes as input a reference to an element and will mask all critical alarms of this element. It does so by using a *SetAlarmStateMessage* and includes an identifier reference to the alarm it should mask, but this identifier still uses the old style of referring to an alarm, i.e. a **DataMiner ID/alarm ID** integer combination. This is must be changed to a **tree ID** instead. |
| 105 | + |
| 106 | +1. Open the *Mask Critical Alarms* script in the Automation app, scroll down, and click *Validate* to check for errors and warnings. |
| 107 | + |
| 108 | + You will see that a warning is detected. |
| 109 | + |
| 110 | +  |
| 111 | + |
| 112 | + Note that you could also open the script via DIS in Visual Studio instead, if you have this installed. In that case, if you target the *Skyline.DataMiner.Dev.Automation* package version 10.5.1 or higher, you will also see an obsolete warning for this script. |
| 113 | + |
| 114 | +1. Update the code in the *foreach* block (line 85) as follows: |
| 115 | + |
| 116 | + Before: |
| 117 | + |
| 118 | + ```csharp |
| 119 | + var maskRequest = new SetAlarmStateMessage(); |
| 120 | + maskRequest.DataMinerID = alarm.DataMinerID; |
| 121 | + maskRequest.AlarmId = alarm.AlarmID; |
| 122 | + maskRequest.DesiredStatus = AlarmUserStatus.Mask; |
| 123 | + maskRequests.Add(maskRequest); |
| 124 | + ``` |
| 125 | + |
| 126 | + After: |
| 127 | + |
| 128 | + ```csharp |
| 129 | + var maskRequest = new SetAlarmStateMessage(alarm.TreeID, AlarmUserStatus.Mask, ""); |
| 130 | + maskRequests.Add(maskRequest); |
| 131 | + ``` |
| 132 | + |
| 133 | +1. Click *Validate* again to see if all warnings and errors are gone. |
| 134 | + |
| 135 | +  |
| 136 | + |
| 137 | +1. Click *Execute* to run the script and test if it still works correctly. |
| 138 | + |
| 139 | +1. If any other scripts or protocols are shown in the alarm ID usage summary, update these in a similar way to make sure they refer to the tree ID or alarm tree ID and validate and test them. |
| 140 | + |
| 141 | + For detailed information, refer to [Preparing scripts and connectors for Swarming](xref:SwarmingPrepare) |
| 142 | + |
| 143 | +1. Run the the *Enable Swarming* script again and click the *Analyze* button again. |
| 144 | + |
| 145 | + If you have indeed correctly updated all scripts and protocols, a new button will be displayed at the bottom of the window. If you do not see this button, check which scripts or protocols still need to be updated and adjust them as mentioned above. |
| 146 | + |
| 147 | +  |
| 148 | + |
| 149 | +1. Click *Restart DMS and enable Swarming*. |
| 150 | + |
| 151 | + The script will now double-check the requirements (which will again take some time), enable Swarming, and restart DataMiner. |
| 152 | + |
| 153 | + > [!IMPORTANT] |
| 154 | + > This will restart all DataMiner Agents in your DMS. |
| 155 | +
|
| 156 | +## Step 5: Swarm your first element |
| 157 | + |
| 158 | +Once DataMiner has restarted, you can test the Swarming functionality by moving an element from one host to another host in your DMS. You will only be able to follow these steps if you are using a DataMiner System consisting of multiple Agents. |
| 159 | + |
| 160 | +1. Go to *System Center* > *Agents* > *Status* and click the *Swarm* button in the lower right corner. |
| 161 | + |
| 162 | + If you see a *Migrate* button here instead, this means Swarming has not been successfully enabled. |
| 163 | + |
| 164 | +  |
| 165 | + |
| 166 | +1. On the left, select the test element you created in [step 2](#step-2-create-a-basic-test-element). |
| 167 | + |
| 168 | + Note that you can select more elements to swarm if you want, but keep in mind that swarming an element involves an element restart, which will result in a brief downtime of the element. |
| 169 | + |
| 170 | +1. On the right, select the destination DMA. |
| 171 | + |
| 172 | +  |
| 173 | + |
| 174 | +1. Click *Swarm*. |
| 175 | + |
| 176 | + A message will be displayed when the element has been successfully swarmed: |
| 177 | + |
| 178 | +  |
| 179 | + |
| 180 | +> [!TIP] |
| 181 | +> For more details about Swarming elements, see [Swarming elements](xref:SwarmingElements). |
0 commit comments