Merge pull request #153 from Icinga:feature/support_knowledgebase_id_on_exception

Feature: Adds support for adding a knowledge base id to exceptions

Adds support to add a knowledge base id to Exit-IcingaThrowException for easier referencing. This should mostly be used for custom messages, as we should track the main knowledge base id's inside the messages directly

Author: LordHepipud

doc/31-Changelog.md

@@ -22,6 +22,7 @@ Released closed milestones can be found on [GitHub](https://github.com/Icinga/ic
 * [#134](https://github.com/Icinga/icinga-powershell-framework/pull/134) Adds Cmdlet `Test-IcingaWindowsInformation` to check if a WMI class exist and if we can fetch data from it. In addition we add support for binary value comparison with the new Cmdlet `Test-IcingaBinaryOperator`
 * [#142](https://github.com/Icinga/icinga-powershell-framework/pull/142) **Experimental:** Adds feature to cache the Framework code into a single file to speed up the entire loading process, mitigating the impact on performance on systems with few CPU cores. You enable disables this feature by using `Enable-IcingaFrameworkCodeCache` and `Disable-IcingaFrameworkCodeCache`. Updating the cache is done with `Write-IcingaFrameworkCodeCache`
 * [#149](https://github.com/Icinga/icinga-powershell-framework/pull/149) Adds support to add Wmi permissions for a specific user and namespace with `Add-IcingaWmiPermissions`. In addition you can remove users from Wmi namespaces by using `Remove-IcingaWmiPermissions`
+* [#153](https://github.com/Icinga/icinga-powershell-framework/pull/153) Adds support to add a knowledge base id to `Exit-IcingaThrowException` for easier referencing. This should mostly be used for custom messages, as we should track the main knowledge base id's inside the messages directly. Native messages should be split in a hashtable with a `Message` and `IWKB` key
 * [#155](https://github.com/Icinga/icinga-powershell-framework/pull/155) Adds support to write all objects collected by `Get-IcingaWindowsInformation` into the Windows EventLog in case the debug output for the Icinga PowerShell Framework is enabled.
 * [#162](https://github.com/Icinga/icinga-powershell-framework/pull/162) Adds feature to test the length of plugin custom variables during config generation and throws error in case the total length is bigger than 64 digits, as imports into the Icinga Director by using baskets is not possible otherwise
 * [#164](https://github.com/Icinga/icinga-powershell-framework/pull/164) Adds `exit` after calling `icinga` on Windows Terminal integration to ensure the shell will close in case the Icinga shell is closed

lib/icinga/exception/Exit-IcingaThrowException.psm1

@@ -4,9 +4,10 @@ function Exit-IcingaThrowException()
         [string]$InputString,
         [string]$StringPattern,
         [string]$CustomMessage,
-        [string]$ExceptionThrown,
+        $ExceptionThrown,
         [ValidateSet('Permission', 'Input', 'Configuration', 'Connection', 'Unhandled', 'Custom')]
         [string]$ExceptionType    = 'Unhandled',
+        [string]$KnowledgeBaseId,
         [switch]$Force
     );
 
@@ -49,6 +50,12 @@ function Exit-IcingaThrowException()
     }
 
     [string]$ExceptionName = '';
+    [string]$ExceptionIWKB = $KnowledgeBaseId;
+
+    if ($ExceptionThrown -is [hashtable]) {
+        $ExceptionIWKB   = $ExceptionThrown.IWKB;
+        $ExceptionThrown = $ExceptionThrown.Message;
+    }
 
     if ($null -ne $ExceptionMessageLib) {
         foreach ($definedError in $ExceptionMessageLib.Keys) {
@@ -67,15 +74,24 @@ function Exit-IcingaThrowException()
         );
     }
 
-    $OutputMessage = '{0}: Icinga {5} Error was thrown: {3}: {4}{1}{1}{2}';
+    if ([string]::IsNullOrEmpty($ExceptionIWKB) -eq $FALSE) {
+        $ExceptionIWKB = [string]::Format(
+            '{0}{0}Further details can be found on the Icinga for Windows Knowledge base: https://icinga.com/docs/windows/latest/doc/knowledgebase/{1}',
+            (New-IcingaNewLine), 
+            $ExceptionIWKB
+        );
+    }
+
+    $OutputMessage = '{0}: Icinga {6} Error was thrown: {4}: {5}{2}{2}{3}{1}';
     if ([string]::IsNullOrEmpty($CustomMessage) -eq $TRUE) {
-        $OutputMessage = '{0}: Icinga {5} Error was thrown: {3}{1}{1}{2}{4}';
+        $OutputMessage = '{0}: Icinga {6} Error was thrown: {4}{2}{2}{3}{5}{1}';
     }
 
     $OutputMessage = [string]::Format(
         $OutputMessage,
         $IcingaEnums.IcingaExitCodeText.($IcingaEnums.IcingaExitCode.Unknown),
-        "`r`n",
+        $ExceptionIWKB,
+        (New-IcingaNewLine),
         $ExceptionThrown,
         $ExceptionName,
         $CustomMessage,

lib/icinga/exception/Icinga_IcingaExceptionEnums.psm1

@@ -7,8 +7,14 @@
 [hashtable]$Permission = @{
     PerformanceCounter = 'A Plugin failed to fetch Performance Counter information. This may be caused when the used Service User is not permitted to access these information. To fix this, please add the User the Icinga Agent is running on into the "Performance Log Users" group and restart the service.';
     CacheFolder        = "A plugin failed to write new data into the configured cache directory. Please update the permissions of this folder to allow write access for the user the Icinga Service is running with or use another folder as cache directory.";
-    CimInstance        = 'The user you are running this command as does not have permission to access the requested Cim-Object. To fix this, please add the user the Agent is running with to the "Remote Management Users" groups and grant access to the WMI branch for the Class/Namespace mentioned above and add the permission "Remote enable". Further details can be found here: https://docs.microsoft.com/en-us/previous-versions/windows/it-pro/windows-server-2008-R2-and-2008/cc771551(v=ws.11)';
-    WMIObject          = 'The user you are running this command as does not have permission to access the requested Wmi-Object. To fix this, please add the user the Agent is running with to the "Remote Management Users" groups and grant access to the WMI branch for the Class/Namespace mentioned above and add the permission "Remote enable". Further details can be found here: https://docs.microsoft.com/en-us/previous-versions/windows/it-pro/windows-server-2008-R2-and-2008/cc771551(v=ws.11)';
+    CimInstance        = @{
+        'Message' = 'The user you are running this command as does not have permission to access the requested Cim-Object. To fix this, please add the user the Agent is running with to the "Remote Management Users" groups and grant access to the WMI branch for the Class/Namespace mentioned above and add the permission "Remote enable".';
+        'IWKB'    = 'IWKB000001';
+    }
+    WMIObject          = @{
+        'Message' = 'The user you are running this command as does not have permission to access the requested Wmi-Object. To fix this, please add the user the Agent is running with to the "Remote Management Users" groups and grant access to the WMI branch for the Class/Namespace mentioned above and add the permission "Remote enable".';
+        'IWKB'    = 'IWKB000001';
+    }
     WindowsUpdate      = 'The user you are running this command as does not have permission to access the Windows Update ComObject "Microsoft.Update.Session". In order to fetch currently installed and pending updates, please grant the user the required permissions for fetching this information.';
 };
 
@@ -20,7 +26,7 @@
     MultipleUnitUsage       = 'Failed to convert your Icinga threshold units as you were trying to convert values with a different type of unit category. This feature only supports the conversion of one unit category. For example you can not convert 20MB:10d in the same call, as size and time units are not compatible.';
     CimClassNameUnknown     = 'The provided class name you try to fetch with Get-CimInstance is not known on this system.';
     WmiObjectClassUnknown   = 'The provided class name you try to fetch with Get-WmiObject is not known on this system.';
-    MSSQLCredentialHandling = 'The connection to MSSQL was not possbible because your login credential was not correct.';
+    MSSQLCredentialHandling = 'The connection to MSSQL was not possible because your login credential was not correct.';
     MSSQLCommandMissing     = 'Failed to build a SQL query'
 };