Skip to content

Bulk Operation commands and improved support for custom powershell functions
Compare
Choose a tag to compare
@reubenmiller reubenmiller released this 17 Jan 21:05
· 1183 commits to master since this release
v1.9.0
bae382b

New features

  • Added bulk operations commands

    PowerShell

    • Get-BulkOperationCollection
    • Get-BulkOperation
    • New-BulkOperation
    • Update-BulkOperation
    • Remove-BulkOperation

    Bash/zsh

    • c8y bulkOperations list
    • c8y bulkOperations create
    • c8y bulkOperations get
    • c8y bulkOperations update
    • c8y bulkOperations delete

  • Get-OperationCollection supports bulkOperationId parameter to return operations related to a specific bulk operation id

  • Added helpers function to make creating custom functions easier and which behave like native PSc8y cmdlets.

    • Get-ClientCommonParameters - Get common PSc8y parameters so they can be added to external using PowerShell's DynamicParam block
    • Add-ClientResponseType - Add a type to a list of devices if the -Raw parameter is not being used

    Example

    The following function get a list of software items stored as managed objects in Cumulocity.

    The cmdlet only needs to define one parameter $Name for the custom logic. The following parameters are inherited via the Get-ClientCommonParameters call in the DynamicParam block

    • Pagination parameters: PageSize, WithTotalPages, TotalPages, CurrentPage, IncludeAll
    • Pagination parameters: Session
    • General parameters: TimeoutSec, Raw, OutputFile
    Function Get-SoftwareCollection {
    [cmdletbinding(
        SupportsShouldProcess = $true,
        ConfirmImpact = "None"
    )]
    Param(
        # Software name
        [string]
        $Name = "*"
    )
    # Inherit common parameters from PSc8y module
    DynamicParam { PSc8y\Get-ClientCommonParameters -Type "Collection" }

    Process {
        $Query = "type eq 'c8y_Software' and name eq '{0}'" -f $Name
        $null = $PSBoundParameters.Remove("Name")

        Find-ManagedObjectCollection -Query $Query @PSBoundParameters `
            | Select-Object `
            | Add-ClientResponseType -Type "application/vnd.com.nsn.cumulocity.customSoftware+json"
    }
}

Minor improvements

  • "owner" is field is left untouched in the -Data parameter allowing the user to change it if required.

    Update-ManagedObject -Id 12345 -Data @{owner="myuser"}

  • Cumulocity API error messages are prefixed with "Server error." to make it more clear that the error is due to an API call and not the client.

    PS /workspaces/go-c8y-cli> Get-AuditRecord 12345                        

WARNING: c8y returned a non-zero exit code. code=1
Write-Error: /workspaces/go-c8y-cli/tools/PSc8y/dist/PSc8y/PSc8y.psm1:3657:13
Line |
3657 |              Invoke-ClientCommand `
    |              ~~~~~~~~~~~~~~~~~~~~~~
    | Server error. general/internalError

PS /workspaces/go-c8y-cli> Get-Alarm 12345                              


WARNING: c8y returned a non-zero exit code. code=1
Write-Error: /workspaces/go-c8y-cli/tools/PSc8y/dist/PSc8y/PSc8y.psm1:2742:13
Line |
2742 |              Invoke-ClientCommand `
    |              ~~~~~~~~~~~~~~~~~~~~~~
    | Server error. alarm/Not Found: Finding alarm from database failed : No alarm for gid '12345'!

  • PSc8y command automatically detect the -WhatIf and -Force parameters from any parent commands. This reduces the amount of boilerplate code.

    Example: Custom command to send a restart operation

    Function New-MyCustomRestartOperation {
    [cmdletbinding(
        SupportsShouldProcess = $true,
        ConfirmImpact = "High"
    )]
    Param(
        [Parameter(
            Mandatory = $true,
            Position = 0
        )]
        [object[]] $Device,

        [switch] $Force
    )

    Process {
        foreach ($iDevice in (Expand-Device $Device)) {
            New-Operation `
                -Device $iDevice `
                -Description "Restart device" `
                -Data @{ c8y_Restart = @{}}
        }
    }
}

    Normally when using New-Operation within your command, you need to pass the WhatIf and Force parameter values like so:

    New-Operation `
    -Device $iDevice `
    -Data @{ c8y_Restart = @{}} `
    -WhatIf:$WhatIfPreference `
    -Force:$Force

    However now all PSc8y commands will automatically inherit these values.

    New-MyCustomOperation -Device 12345 -WhatIf
New-MyCustomOperation -Device 12345 -Force

    The variable inheritance can be disabled by setting the following environment variable

    $env:C8Y_DISABLE_INHERITANCE = $true

  • pwsh docker image improvements

    • Enabled pwsh tab completion by default
    • Added vim text editor

  • Get-DeviceCollection supports OrderBy parameter to sort

    Example: Get a list of devices sorting by name in descending order

    PowerShell

    Get-DeviceCollection -OrderBy "name desc"

    Bash/zsh

    c8y devices list --orderBy "name desc"

  • Test cmdlets supports the -Time parameter to be able to control the timestamp of created entity. By default it will use "0s" (i.e. now).

    • New-TestAlarm
    • New-TestEvent
    • New-TestMeasurement

  • Get-SessionHomePath Added public PowerShell cmdlet to retrieve the path where the session are stored

  • New cmdlet Register-ClientArgumentCompleter to enable other modules to add argument completion to PSc8y parameters like Session and Template

    • Note: -Force needs to be used if your command uses Dynamic Parameters
Assets 7
Loading