Refactor Get-NCScheduledTasks and update access group functions

[theonlytruebigmac]

This pull request updates the module to version 1.8.1 and includes several bug fixes, standardizations, and code cleanups across multiple cmdlets. The most significant changes are the removal of dead parameters from Get-NCScheduledTasks (making -TaskId mandatory), improved consistency in parameter casing and variable usage, and updates to endpoint usage for some cmdlets. There are also improvements to body construction for group creation cmdlets and consistent use of begin/process blocks for API lifecycle management.

Cmdlet Parameter and API Usage Fixes:

• Get-NCScheduledTasks: Removed unused parameters (-All, -PageNumber, -PageSize, -SortBy, -SortOrder) that previously threw errors; -TaskId is now mandatory, and the documentation clarifies there is no bulk-list endpoint. Added a test to assert -TaskId is required. [1] [2]
• Get-NCStandardPsaCustomerMapping: Updated to use the new endpoint /api/standard-psa/customer/{id}/mappings instead of the deprecated one. [1] [2]
• New-NCOrgAccessGroup / New-NCDeviceAccessGroup: Optional orgUnitIds/deviceIds/userIds arrays are only sent if provided (not as null). [1] [2]

Parameter Casing and Consistency:

• Standardized PascalCase for parameter references in comment-based help and in the body construction for New-NCCustomer, New-NCSite, New-NCServiceOrg, Get-NCJobStatus, Get-NCDefaultDeviceProperty, and others. [1] [2] [3] [4] [5] [6] [7]

Codebase Simplification and Formatting:

• Cleaned up indentation, removed extra blank lines, and simplified verbose logging and endpoint construction in several cmdlets (Get-NCJobStatus, Get-NCDefaultDeviceProperty, Get-NCDeviceAssets, Get-NCDeviceServices). [1] [2] [3] [4] [5]

Lifecycle Management Consistency:

• Added begin/process blocks for API instance lifecycle consistency in Get-NCFilters, New-NCServiceOrg, and New-NCSite. [1] [2] [3]

Testing and Miscellaneous:

• Updated SpecDrift.Tests.ps1 to read the root spec.json instead of a fixture file.
• Bumped module version to 1.8.1.

These changes improve reliability, maintainability, and consistency across the module.

[Copilot]

🟡 Changes recommended

The updated SpecDrift test points to a non-existent spec.json, and the new Get-NCScheduledTasks test does not actually validate that -TaskId is mandatory.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR updates the NCRestAPI PowerShell module to v1.8.1 and refactors several cmdlets to improve consistency (parameter casing, lifecycle blocks), remove non-functional parameters, and align a mapping cmdlet with an updated API endpoint. It also updates/extends Pester tests and the changelog to reflect these behavior changes.

Changes:

• Refactors Get-NCScheduledTasks to require -TaskId and removes non-working paging/bulk parameters; adds a corresponding test.
• Updates Get-NCStandardPsaCustomerMapping to use the newer /api/standard-psa/customer/{id}/mappings endpoint.
• Standardizes cmdlet structure and parameter casing across multiple cmdlets and adjusts access-group body construction to avoid sending null arrays.

File summaries

File	Description
Tests/SpecDrift.Tests.ps1	Changes drift test to read a root OpenAPI spec file (currently points to spec.json).
Tests/NCRestAPI.Tests.ps1	Adds a new Pester test intended to enforce Get-NCScheduledTasks -TaskId requirement.
Public/New-NCSite.ps1	Standardizes help parameter casing and refactors to begin/process with cleaner body construction.
Public/New-NCServiceOrg.ps1	Refactors to begin/process and simplifies request body construction and posting.
Public/New-NCScheduledTask.ps1	Standardizes comment-based help .PARAMETER casing.
Public/New-NCOrgAccessGroup.ps1	Avoids sending orgUnitIds/userIds when omitted.
Public/New-NCDeviceAccessGroup.ps1	Avoids sending deviceIds/userIds when omitted.
Public/New-NCCustomer.ps1	Standardizes PascalCase variable references in body construction and ShouldProcess.
Public/Get-NCStandardPsaCustomerMapping.ps1	Updates endpoint path and adjusts verbose logging/help to match.
Public/Get-NCScheduledTaskStatus.ps1	Standardizes comment-based help parameter casing and examples.
Public/Get-NCScheduledTasks.ps1	Removes dead parameters and makes -TaskId mandatory; updates behavior/docs accordingly.
Public/Get-NCJobStatus.ps1	Simplifies endpoint construction/logging and standardizes casing.
Public/Get-NCFilters.ps1	Introduces begin/process for API lifecycle consistency.
Public/Get-NCDeviceServices.ps1	Standardizes help casing and simplifies verbose/endpoint logic.
Public/Get-NCDeviceAssets.ps1	Simplifies endpoint construction and removes redundant variables/returns.
Public/Get-NCDefaultDeviceProperty.ps1	Simplifies endpoint construction/logging and standardizes casing.
Public/Get-NCApplianceTask.ps1	Standardizes comment-based help parameter casing and examples.
NCRestAPI.psd1	Bumps module version to 1.8.1.
CHANGELOG.md	Adds 1.8.1 entry documenting the refactors and fixes.

Review details

• Files reviewed: 19/21 changed files
• Comments generated: 4
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟡 Changes recommended

The access-group body construction now omits explicitly-passed empty arrays and the new scheduled-tasks test doesn’t actually verify -TaskId is mandatory.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Suppressed comments (3)

Public/New-NCOrgAccessGroup.ps1:79

• The new conditional if ($OrgUnitIds) / if ($UserIds) drops the property when the caller passes an empty array (@()), even if they explicitly provided the parameter. If the API distinguishes between “field omitted” vs “empty list”, this becomes a functional behavior change; prefer checking $null instead so empty arrays are still sent.

    if ($OrgUnitIds) { $body.orgUnitIds = $OrgUnitIds }
    if ($UserIds)    { $body.userIds    = $UserIds }

Public/New-NCDeviceAccessGroup.ps1:73

• The new if ($DeviceIds) / if ($UserIds) checks treat an explicitly-passed empty array (@()) as false and omit the field entirely. To preserve the ability to send an empty list (and only omit when the parameter is not provided), check for $null instead of truthiness.

    if ($DeviceIds) { $body.deviceIds = $DeviceIds }
    if ($UserIds)   { $body.userIds   = $UserIds }

Tests/NCRestAPI.Tests.ps1:322

• This test currently throws because -TaskId '' violates ValidateNotNullOrEmpty(), so it would also have passed before this PR (it doesn’t actually assert that -TaskId is mandatory). Consider asserting the parameter metadata instead to ensure the cmdlet truly requires -TaskId without risking an interactive prompt.

Describe 'Get-NCScheduledTasks parameter enforcement' {
    It 'requires -TaskId (no bulk endpoint)' {
        $cmd = Get-Command Get-NCScheduledTasks
        $paramAttr = $cmd.Parameters['TaskId'].Attributes | Where-Object { $_ -is [System.Management.Automation.ParameterAttribute] } | Select-Object -First 1

• Files reviewed: 19/21 changed files
• Comments generated: 1
• Review effort level: Lite

[Copilot]

🟢 Approval recommended

The changes are cohesive and well-covered by existing patterns/tests, with only minor formatting nits identified.

Review details

• Files reviewed: 19/21 changed files
• Comments generated: 2
• Review effort level: Lite

[Copilot]

🟢 Approval recommended

Changes are cohesive and covered by updated tests, with only minor maintainability nits noted in the access-group body construction.

Review details

Suppressed comments (2)

Public/New-NCOrgAccessGroup.ps1:79

• These if statements are currently unindented relative to the surrounding code and only check $null -ne .... Prefer $PSBoundParameters.ContainsKey(...) (to only send fields the caller supplied) and indent them to match the rest of the function for readability.

if ($null -ne $OrgUnitIds) { $body.orgUnitIds = $OrgUnitIds }
if ($null -ne $UserIds)    { $body.userIds    = $UserIds }

Public/New-NCDeviceAccessGroup.ps1:73

• The conditional additions to $body are not indented like the rest of the function and rely only on $null -ne .... Using $PSBoundParameters.ContainsKey(...) makes it explicit that the caller provided the parameter (and keeps behavior consistent with other cmdlets that only send supplied fields), while fixing the indentation/readability issue.

if ($null -ne $DeviceIds) { $body.deviceIds = $DeviceIds }
if ($null -ne $UserIds)   { $body.userIds   = $UserIds }

• Files reviewed: 19/21 changed files
• Comments generated: 0 new
• Review effort level: Lite