v.2.0.0-beta1 release.

Author: homotechsual

.vscode/settings.json

@@ -4,6 +4,15 @@
         "commandlet",
         "commandlets",
         "Gavsto",
-        "Mikey"
-    ]
+        "Mikey",
+        "Organisation",
+        "Organisations",
+        "organisation",
+        "hashtable",
+        "pluralised",
+        "Homotechsual",
+        "pipelining",
+        "O'Toole"
+    ],
+    "cSpell.language": "en-GB",
 }

CHANGELOG.md

@@ -1,6 +1,24 @@
 # Changelog
 
-## 2023-10-31 - Version 2.0.0-beta1
+Please note that backwards compatibility breaks are prefixed with `{"BC"}` (short for Breaking Change).
+
+## 2023-11-15 - Version 2.0.0-beta1
+
+* {"BC"} Refactoring of error handling to allow PowerShell 5.1 compatibility.
+* {"BC"} Removal / change of the `id` alias on some parameters.
+* {"BC"} Each commandlet now supports pipelining of the "primary" id value. Commandlets which require more than one `id` parameter do not support pipelining except by property name.
+* {"BC"} Rename most `Update-*` commandlets to `Set-*`. Aliases are in place.
+* {"BC"} Removal of all `*-NinjaRMM*` aliases to their `*-NinjaOne*` commandlets.
+* {"BC"} All `Write-Debug` statements are now `Write-Verbose`.
+* Add `-expandActivities` parameter to `Get-NinjaOneActivities`.
+* Add `-expandOverrides` parameter to `Get-NinjaOneDevicePolicyOverrides`.
+* Implement the framework for adding classes to build objects for `POST` endpoints.
+* All commandlets which require an entity to exist will throw an error if the entity with the given id doesn't exist.
+* The base `Get-*` commands for the core entities now throw if no results are returned.
+* Refactor exception catches in Private utility commandlets.
+* Reword error and verbose messaging throughout.
+* Switch all string/variable interpolation to use the `-f` format string operator with single-quoted strings.
+* Add `us2` instance.
 
 ## 2023-10-25 - Version 1.12.3
 

NinjaOne.build.ps1

@@ -226,7 +226,7 @@ if ($UpdateManifest) {
     [System.Version]$Version = $Manifest.Version
 
     if ($ChangeLogVersion -eq $Version) {
-        Throw 'No new version found in CHANGELOG.md'
+        throw 'No new version found in CHANGELOG.md'
     }
 
     Write-Output -InputObject ("Current Module Version: $($Version)")
@@ -257,7 +257,7 @@ if ($PublishModule -and $Configuration -eq 'Production') {
         Publish-Module @params
         Write-Output -InputObject ("$ModuleName PowerShell Module version $($Version) published to the PowerShell Gallery")
     } Catch {
-        Throw $_
+        throw $_
     }
 }
 

NinjaOne.code-workspace

@@ -25,7 +25,15 @@
     "powershell.codeFormatting.whitespaceBeforeOpenBrace": true,
     "powershell.codeFormatting.whitespaceBeforeOpenParen": true,
     "powershell.codeFormatting.whitespaceBetweenParameters": false,
-    "powershell.codeFormatting.whitespaceInsideBrace": true
+    "powershell.codeFormatting.whitespaceInsideBrace": true,
+    "cSpell.words": [
+      "hashtable",
+      "homotechsual",
+      "Homotechsual",
+      "organisation",
+      "Organisation",
+      "pluralised"
+    ]
   },
   "launch": {
     "version": "0.2.0",

NinjaOne.psd1

@@ -169,59 +169,12 @@
 
     # Aliases to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no aliases to export.
     AliasesToExport = @(
-        'Connect-NinjaRMM',
-        'Find-NinjaRMMDevices',
-        'Get-NinjaRMMActivities',
-        'Get-NinjaRMMAlerts',
         'Get-NinjaOneBoards',
-        'Get-NinjaRMMDeviceCustomFields',
-        'Get-NinjaRMMDeviceJobs',
-        'Get-NinjaRMMDeviceLastLoggedOnUser',
-        'Get-NinjaRMMDeviceOSPatches',
-        'Get-NinjaRMMDeviceProcessors',
-        'Get-NinjaRMMDeviceVolumes',
-        'Get-NinjaRMMDeviceSoftwarePatches',
-        'Get-NinjaRMMDeviceSoftwarePatchInstalls',
-        'Get-NinjaRMMDeviceDisks',
-        'Get-NinjaRMMDevices',
-        'Get-NinjaRMMGroupMembers',
-        'Get-NinjaRMMGroups',
-        'Get-NinjaRMMJobs',
-        'Get-NinjaRMMLocations',
         'Get-NinjaOneOrganizationCustomFields',
         'Get-NinjaRMMOrganisationDocuments',
         'Get-NinjaRMMOrganizationDocuments',
         'Get-NinjaOneOrganizationDocuments',
-        'Get-NinjaRMMOrganisations',
-        'Get-NinjaRMMOrganizations',
         'Get-NinjaOneOrganizations',
-        'Get-NinjaRMMPolicies',
-        'Get-NinjaRMMRoles',
-        'Get-NinjaRMMSoftwareProducts',
-        'Get-NinjaRMMTasks',
-        'Get-NinjaRMMUsers',
-        'Get-NinjaRMMCustomFields',
-        'Get-NinjaRMMAntivirusStatus',
-        'Get-NinjaRMMAntivirusThreats',
-        'Get-NinjaRMMComputerSystems',
-        'Get-NinjaRMMCustomFields',
-        'Get-NinjaRMMDeviceHealth',
-        'Get-NinjaRMMDisks',
-        'Get-NinjaRMMLoggedOnUsers',
-        'Get-NinjaRMMOperatingSystems',
-        'Get-NinjaRMMOSPatches',
-        'Get-NinjaRMMOSPatchInstalls',
-        'Get-NinjaRMMProcessors',
-        'Get-NinjaRMMRAIDControllers',
-        'Get-NinjaRMMRAIDDrives',
-        'Get-NinjaRMMSoftwareInventory',
-        'Get-NinjaRMMSoftwarePatches',
-        'Get-NinjaRMMSoftwarePatchInstalls',
-        'Get-NinjaRMMVolumes',
-        'Get-NinjaRMMWindowsServices',
-        'Get-NinjaRMMDeviceDashboardURL',
-        'Get-NinjaRMMDeviceScriptingOptions',
-        'Get-NinjaRMMInstaller',
         'New-NinjaOneOrganization',
         'Update-NinjaOneOrganization',
         'Update-NinjaOneOrganizationDocument'
@@ -230,7 +183,18 @@
         'Set-NinjaOneOrganizationCustomFields',
         'Update-NinjaOneLocationCustomFields',
         'Update-NinjaOneDeviceCustomFields',
-        'Get-NinjaOneDevice'
+        'Get-NinjaOneDevice',
+        'Set-NinjaOneWebhook',
+        'Update-NinjaOneDevice',
+        'Update-NinjaOneDeviceApproval',
+        'Update-NinjaOneDeviceCustomFields',
+        'Update-NinjaOneDeviceMaintenance',
+        'Update-NinjaOneLocation',
+        'Update-NinjaOneNodeRolePolicyAssignment',
+        'Update-NinjaOneOrganisation',
+        'Update-NinjaOneOrganisationCustomFields',
+        'Update-NinjaOneTicket',
+        'Update-NinjaOneWindowsServiceConfiguration'
     )
 
     # DSC resources to export from this module

NinjaOne.psm1

@@ -48,67 +48,31 @@ foreach ($Function in @($Functions)) {
     'oc' = 'https://oc.ninjarmm.com'
     'us' = 'https://app.ninjarmm.com'
     'ca' = 'https://ca.ninjarmm.com'
+    'us2' = 'https://us2.ninjarmm.com'
 }
 New-Alias -Name 'Connect-NinjaRMM' -Value 'Connect-NinjaOne'
 New-Alias -Name 'Find-NinjaRMMDevices' -Value 'Find-NinjaOneDevices'
-New-Alias -Name 'Get-NinjaRMMActivities' -Value 'Get-NinjaOneActivities'
-New-Alias -Name 'Get-NinjaRMMAlerts' -Value 'Get-NinjaOneAlerts'
-New-Alias -Name 'Get-NinjaRMMDeviceCustomFields' -Value 'Get-NinjaOneDeviceCustomFields'
-New-Alias -Name 'Get-NinjaRMMDeviceDisks' -Value 'Get-NinjaOneDeviceDisks'
-New-Alias -Name 'Get-NinjaRMMDeviceLastLoggedOnUser' -Value 'Get-NinjaOneDeviceLastLoggedOnUser'
-New-Alias -Name 'Get-NinjaRMMDeviceOSPatches' -Value 'Get-NinjaOneDeviceOSPatches'
-New-Alias -Name 'Get-NinjaRMMDeviceOSPatchInstalls' -Value 'Get-NinjaOneDeviceOSPatchInstalls'
-New-Alias -Name 'Get-NinjaRMMDeviceProcessors' -Value 'Get-NinjaOneDeviceProcessors'
-New-Alias -Name 'Get-NinjaRMMDevices' -Value 'Get-NinjaOneDevices'
-New-Alias -Name 'Get-NinjaRMMDeviceSoftwarePatches' -Value 'Get-NinjaOneDeviceSoftwarePatches'
-New-Alias -Name 'Get-NinjaRMMDeviceSoftwarePatchInstalls' -Value 'Get-NinjaOneDeviceSoftwarePatchInstalls'
-New-Alias -Name 'Get-NinjaRMMDeviceVolumes' -Value 'Get-NinjaOneDeviceVolumes'
-New-Alias -Name 'Get-NinjaRMMDeviceWindowsServices' -Value 'Get-NinjaOneDeviceWindowsServices'
-New-Alias -Name 'Get-NinjaRMMGroupMembers' -Value 'Get-NinjaOneGroupMembers'
-New-Alias -Name 'Get-NinjaRMMGroups' -Value 'Get-NinjaOneGroups'
-New-Alias -Name 'Get-NinjaRMMJobs' -Value 'Get-NinjaOneJobs'
-New-Alias -Name 'Get-NinjaRMMLocations' -Value 'Get-NinjaOneLocations'
-New-Alias -Name 'Get-NinjaRMMOrganisationDocuments' -Value 'Get-NinjaOneOrganisationDocuments'
-New-Alias -Name 'Get-NinjaRMMOrganizationDocuments' -Value 'Get-NinjaOneOrganizationDocuments'
+New-Alias -Name 'Get-NinjaOneBoards' -Value 'Get-NinjaOneTicketBoards'
+New-Alias -Name 'Get-NinjaOneDevice' -Value 'Get-NinjaOneDevices'
+New-Alias -Name 'Get-NinjaOneDeviceSoftwareProducts' -Value 'Get-NinjaOneSoftwareProducts'
+New-Alias -Name 'Get-NinjaOneOrganizationCustomFields' -Value 'Get-NinjaOneOrganisationCustomFields'
 New-Alias -Name 'Get-NinjaOneOrganizationDocuments' -Value 'Get-NinjaOneOrganisationDocuments'
-New-Alias -Name 'Get-NinjaRMMOrganisations' -Value 'Get-NinjaOneOrganisations'
-New-Alias -Name 'Get-NinjaRMMOrganizations' -Value 'Get-NinjaOneOrganisations'
 New-Alias -Name 'Get-NinjaOneOrganizations' -Value 'Get-NinjaOneOrganisations'
-New-Alias -Name 'Get-NinjaRMMPolicies' -Value 'Get-NinjaOnePolicies'
-New-Alias -Name 'Get-NinjaRMMRoles' -Value 'Get-NinjaOneRoles'
-New-Alias -Name 'Get-NinjaRMMSoftwareProducts' -Value 'Get-NinjaOneSoftwareProducts'
-New-Alias -Name 'Get-NinjaRMMTasks' -Value 'Get-NinjaOneTasks'
-New-Alias -Name 'Get-NinjaRMMUsers' -Value 'Get-NinjaOneUsers'
-New-Alias -Name 'Get-NinjaRMMDeviceDashboardURL' -Value 'Get-NinjaOneDeviceDashboardURL'
-New-Alias -Name 'Get-NinjaRMMDeviceScriptingOptions' -Value 'Get-NinjaOneDeviceScriptingOptions'
-New-Alias -Name 'Get-NinjaRMMInstaller' -Value 'Get-NinjaOneInstaller'
-New-Alias -Name 'Get-NinjaRMMAntivirusStatus' -Value 'Get-NinjaOneAntivirusStatus'
-New-Alias -Name 'Get-NinjaRMMAntivirusThreats' -Value 'Get-NinjaOneAntivirusThreats'
-New-Alias -Name 'Get-NinjaRMMComputerSystems' -Value 'Get-NinjaOneComputerSystems'
-New-Alias -Name 'Get-NinjaRMMCustomFields' -Value 'Get-NinjaOneCustomFields'
-New-Alias -Name 'Get-NinjaRMMDeviceHealth' -Value 'Get-NinjaOneDeviceHealth'
-New-Alias -Name 'Get-NinjaRMMDisks' -Value 'Get-NinjaOneDisks'
-New-Alias -Name 'Get-NinjaRMMLoggedOnUsers' -Value 'Get-NinjaOneLoggedOnUsers'
-New-Alias -Name 'Get-NinjaRMMOperatingSystems' -Value 'Get-NinjaOneOperatingSystems'
-New-Alias -Name 'Get-NinjaRMMOSPatches' -Value 'Get-NinjaOneOSPatches'
-New-Alias -Name 'Get-NinjaRMMOSPatchInstalls' -Value 'Get-NinjaOneOSPatchInstalls'
-New-Alias -Name 'Get-NinjaRMMProcessors' -Value 'Get-NinjaOneProcessors'
-New-Alias -Name 'Get-NinjaRMMRAIDControllers' -Value 'Get-NinjaOneRAIDControllers'
-New-Alias -Name 'Get-NinjaRMMRAIDDrives' -Value 'Get-NinjaOneRAIDDrives'
-New-Alias -Name 'Get-NinjaRMMSoftwareInventory' -Value 'Get-NinjaOneSoftwareInventory'
-New-Alias -Name 'Get-NinjaRMMSoftwarePatches' -Value 'Get-NinjaOneSoftwarePatches'
-New-Alias -Name 'Get-NinjaRMMSoftwarePatchInstalls' -Value 'Get-NinjaOneSoftwarePatchInstalls'
-New-Alias -Name 'Get-NinjaRMMVolumes' -Value 'Get-NinjaOneVolumes'
-New-Alias -Name 'Get-NinjaRMMWindowsServices' -Value 'Get-NinjaOneWindowsServices'
 New-Alias -Name 'New-NinjaOneOrganization' -Value 'New-NinjaOneOrganisation'
-New-Alias -Name 'Update-NinjaOneOrganization' -Value 'Update-NinjaOneOrganisation'
-New-Alias -Name 'Update-NinjaOneOrganizationDocument' -Value 'Update-NinjaOneOrganisationDocument'
-New-Alias -Name 'Get-NinjaOneBoards' -Value 'Get-NinjaOneTicketBoards'
-New-Alias -Name 'Update-NinjaOneOrganisationCustomFields' -Value 'Set-NinjaOneOrganisationCustomFields'
+New-Alias -Name 'Set-NinjaOneOrganizationCustomFields' -Value 'Set-NinjaOneOrganisationCustomFields'
+New-Alias -Name 'Set-NinjaOneWebhook' -Value 'Update-NinjaOneWebhook'
+New-Alias -Name 'Update-NinjaOneDevice' -Value 'Set-NinjaOneDevice'
+New-Alias -Name 'Update-NinjaOneDeviceApproval' -Value 'Set-NinjaOneDeviceApproval'
+New-Alias -Name 'Update-NinjaOneDeviceCustomFields' -Value 'Set-NinjaOneDeviceCustomFields'
+New-Alias -Name 'Update-NinjaOneDeviceMaintenance' -Value 'Set-NinjaOneDeviceMaintenance'
+New-Alias -Name 'Update-NinjaOneLocation' -Value 'Set-NinjaOneLocation'
 New-Alias -Name 'Update-NinjaOneLocationCustomFields' -Value 'Set-NinjaOneLocationCustomFields'
+New-Alias -Name 'Update-NinjaOneNodeRolePolicyAssignment' -Value 'Set-NinjaOneNodeRolePolicyAssignment'
+New-Alias -Name 'Update-NinjaOneOrganisation' -Value 'Set-NinjaOneOrganisation'
+New-Alias -Name 'Update-NinjaOneOrganisationCustomFields' -Value 'Set-NinjaOneOrganisationCustomFields'
+New-Alias -Name 'Update-NinjaOneOrganization' -Value 'Set-NinjaOneOrganisation'
 New-Alias -Name 'Update-NinjaOneOrganizationCustomFields' -Value 'Set-NinjaOneOrganisationCustomFields'
-New-Alias -Name 'Set-OrganizationCustomFields' -Value 'Set-NinjaOneOrganisationCustomFields'
-New-Alias -Name 'Update-NinjaOneDeviceCustomFields' -Value 'Set-NinjaOneDeviceCustomFields'
-New-Alias -Name 'Get-NinjaOneOrganizationCustomFields' -Value 'Get-NinjaOneOrganisationCustomFields'
-New-Alias -Name 'Get-NinjaOneDevice' -Value 'Get-NinjaOneDevices'
+New-Alias -Name 'Update-NinjaOneOrganizationDocument' -Value 'Update-NinjaOneOrganisationDocument'
+New-Alias -Name 'Update-NinjaOneTicket' -Value 'Update-NinjaOneTicket'
+New-Alias -Name 'Update-NinjaOneWindowsServiceConfiguration' -Value 'Set-NinjaOneWindowsServiceConfiguration'
 Export-ModuleMember -Function $Functions.BaseName -Alias *

PSScriptAnalyzerSettings.psd1

@@ -45,7 +45,7 @@
         'PSUseDeclaredVarsMoreThanAssignments',
         'PSUsePSCredentialType',
         'PSUseShouldProcessForStateChangingFunctions',
-        'PSUseSingularNouns',
+        #'PSUseSingularNouns',
         'PSUseLowerCaseForBooleanVariables',
         'PSUseLowerCaseForBuiltInFunctions',
         'PSUseLowerCaseForParameters',

Private/ConvertTo-UnixEpoch.ps1

@@ -29,5 +29,5 @@ function ConvertTo-UnixEpoch {
     $UniversalDateTime = $DateTime.ToUniversalTime()
     $UnixEpochTimestamp = Get-Date -Date $UniversalDateTime -UFormat %s
     Write-Verbose "Converted $DateTime to Unix Epoch timestamp $UnixEpochTimestamp"
-    Return $UnixEpochTimestamp
+    return $UnixEpochTimestamp
 }

Private/Get-TokenExpiry.ps1

@@ -19,5 +19,5 @@ function Get-TokenExpiry {
     $Now = Get-Date
     $ExpiryDateTime = $Now.AddSeconds($ExpiresIn)
     Write-Verbose "Calcuated token expiry as $ExpiryDateTime"
-    Return $ExpiryDateTime
+    return $ExpiryDateTime
 }

Private/Invoke-NinjaOnePreFlightCheck.ps1

@@ -0,0 +1,29 @@
+using namespace System.Management.Automation
+function Invoke-NinjaOnePreFlightCheck {
+    [CmdletBinding()]
+    param(
+        # Skip the connection checks.
+        [Parameter()]
+        [Switch]$SkipConnectionChecks
+    )
+    if (-not $SkipConnectionChecks) {
+        if ($null -eq $Script:NRAPIConnectionInformation) {
+            $NoConnectionInformationException = [System.Exception]::New("Missing NinjaOne connection information, please run 'Connect-NinjaOne' first.")
+            $ErrorRecord = [ErrorRecord]::New($NoConnectionInformationException, 'NoConnectionInformation', 'AuthenticationError', 'NinjaOnePreFlightCheck')
+            
+            $PSCmdlet.throwTerminatingError($ErrorRecord)
+        }
+        if (($null -eq $Script:HAPIAuthToken) -and ($null -eq $AllowAnonymous)) {
+            $NoAuthTokenException = [System.Exception]::New("Missing Halo authentication token, please run 'Connect-HaloAPI' first.")
+            $ErrorRecord = [ErrorRecord]::New($NoAuthTokenException, 'NoAuthToken', 'AuthenticationError', 'NinjaOnePreFlightCheck')
+
+            $PSCmdlet.throwTerminatingError($ErrorRecord)
+        }
+    } else {
+        Write-Verbose 'Skipping connection checks.'
+    }
+    if ($PSEdition -eq 'Desktop') {
+        
+        
+    }
+}