Cumulocity CLI 2.0.0-beta15

Changelog

5615e82 adding delay and delayBefore setting completion for use in c8y settings update
05808e1 removing deprecated setting
5a28131 prevent race conditions when detecting output view
51d3975 refactoring to use exit code constants
3589802 updating docker usage docs
23dcf08 updating docs
ae2c577 updating docs
7faadec adding changelog entry
40648a6 updating autogen code
a40063f adding template support and setting default type value
5c1bab2 updating output data examples

Cumulocity CLI 2.0.0-beta14

Changelog

b6123f2 setting c8y alias before it is referenced in PSc8y module
4893f9b fixing changing of folder ownership on macOS. Using chown instead to be more reliable

Cumulocity CLI 2.0.0-beta13

Changelog

c06bb33 merging docker c8y bash and zsh images to one called c8y-shell which includes bash, zsh and fish
d27729e adding check for empty SUDO_USER env variable

Cumulocity CLI 2.0.0-beta9

Changelog

d75cc3f setting powershell module version from git tag
7f4c50a adding link to release notes
7db7f75 refactoring tests
b947048 removing references to deprecated env variable C8Y_USE_ENVIRONMENT
fe797f2 refactoring tests
e656814 removing unused code
4fae2f8 adding paths to internal templates
72065fb adding templates to powershell module

Improving error handling and request metrics

New Features

• Exit codes are not set to the HTTP exit codes for commands which send a REST request. The https status codes are mapped to exit codes between 0 - 128 to ensure compatibility to different operating systems and applications.

  The full error codes can be found on the new error handling concept page. However a few include:

  • 0 => 0 (REST request was ok)
  • 1 => 401 (Unauthorized)
  • 3 => 403 (Forbidden)
  • 4 => 404 (Not found)
  • 9 => 409 (Conflict/duplicate)
  • 22 => 422 (Unprocessable entity / invalid request)
  • 50 => 500 (Internal server error)

• Added Remove-ApplicationBinary command

  Example: Remove all application binaries related to an application

  PowerShell

  Remove-ApplicationBinary -Application 12345 -BinaryId 9876
  
  # Or remove all application binaries (except the active one) for an application
  Get-ApplicationBinaryCollection -Id 12345 | Remove-ApplicationBinary -Application 12345

  Bash/zsh

  c8y applications deleteApplicationBinary --application 12345 --binaryId 9876

New Features (PSc8y)

• Added support for saving meta information about the requests to the in-built PowerShell InformationVariable common parameter

  Note: This does not currently work when using the -IncludeAll parameter

  Documentation - Request metrics:

  Example: Save request to a variable without sending the request

  New-Device -Name my-test -WhatIf -InformationVariable requestInfo
  $requestInfo

  Output

  What If: Sending [POST] request to [https://example123.my-c8y.com/inventory/managedObjects]
  
  Headers:
  Accept: application/json
  Authorization: Basic asdfasfd........
  Content-Type: application/json
  User-Agent: go-client
  X-Application: go-client
  
  Body:
  {
  "c8y_IsDevice": {},
  "name": "my-test"
  }

  Example: Get the response time of a request

  New-Device -Name my-test -InformationVariable requestInfo
  Write-Host ("Response took {0}" -f $requestInfo.MessageData.responseTime)

  Output

  Response took 172ms
  

• Support for ErrorVariable common variable to save error output to a variable

  Note: This does not currently work when using the -IncludeAll parameter

  Example: Save error output to a variable

  Get-ManagedObject -Id 0 -ErrorVariable "c8yError" -ErrorAction SilentlyContinue
  
  if ($LASTEXITCODE -ne 0) {
      $MainError = $c8yError[-1]
      Write-Error "Something went wrong. details=$MainError"
  }

• Importing PSc8y will enforce Unicode (UTF-8) encoding on the console if the console is not already using UTF-8 (mostly affecting Windows as it does not use UTF-8 by default unlike MacOS and Linux)

  • User will be informed how to add the setting to the PowerShell profile

  • Enforcement of UTF-8 encoding can be disabled by setting

    $env:C8Y_DISABLE_ENFORCE_ENCODING = $true

Minor Changes

• Updated PowerShell version from 7.0 to 7.1.1 inside docker image c8y-pwsh. This fixed a bug when using Foreach-Object -Parallel which would re-import modules instead of re-using it within each runspace.
• PSc8y will enforce PowerShell encoding to UTF8 to prevent encoding issues when sending data to the c8y go binary. The console encoding will be changed when importing PSc8y. UTF8 is the only text encoding supported. This mainly effects Windows, as MacOS and Linux use UTF8 encoding on the console by default.
• Added a global --noColor to the c8y binary to remove console colours from the log messages to make it easier to parse entries. By default PowerShell uses this option when calling the c8y binary as PowerShell handling the coloured log output itself.

Bug fixes

• New-Device fixed bug which prevent the command from creating the managed object
  • Name is no longer mandatory and it does not accepted piped input
• Changed the processing of standard output and error from the c8y binary to prevent read deadlocks when being called from PowerShell module PSc8y. #39

Reduce API calls and added child additions commands

Breaking Changes

• Expand-Device no longer fetches the device managed object when given the id when being called from a function that does not makes use of a "Force" parameter. If you would like the old functionality, then add the new "-Fetch" parameter when calling Expand-Device.

  By default if Expand-Device is called from an interactive function, then the managed object will be looked up in order to provide helpful information to the user in the confirmation prompt. Additionally users writing modules, can force fetching of the device when given an id by using the new -Fetch parameter.

  The change enable a significant reduction in API calls as shown below in the following examples:

  Comparison of total API calls per command to previous PSc8y version

  Previous version: PSc8y=1.9.1

  The following examples show how many api calls are made to Cumulocity.

  # API calls: 1 x GET    (previously 3 x GET!)
  Get-Device 1234
  
  # API calls: 2 x GET    (previously 5 x GET!)
  Get-Device 1234 | Get-Device
  
  # API calls: 1 x GET and 1 x PUT    (prevously 4 x GET and 1 x PUT)
  Get-Device 1234 | Update-Device
  
  # API calls: 1 x POST   (prevously 3 x GET and 1 x POST)
  Add-DeviceToGroup -Group 11111 -NewChildDevice 222222 -ProcessingMode QUIESCENT -Force

  Expand-Device Usage
  Expand-Device was created in order to normalize the input of devices given by the user. Since PSc8y accepts devices either by id, name, object or piped objects, it can make it difficult to handle each of the input types in each function.

  # file: my-script.ps1
  Param(
      [Parameter(
          Mandatory = $true,
          Position = 0,
          ValueFromPipeline = $true,
          ValueFromPipelineByPropertyName = $true
      )]
      [object[]] $Device = ""
  )
  
  foreach ($iDevice in (PSc8y\Expand-Device $Device)) {
      Write-Host ("Dummy api call with device id: /inventory/managedObject/{0}" -f $iDevice.id)
  }

  By writing it like this the user can call the function in the following ways with the same code.

  # Pass array item
  ./my-script.ps1 -Device 12345
  
  # array of items mixing ids with names
  ./my-script.ps1 -Device "myDevicename", 1234
  
  # using pipelines from other PSc8y cmdlets
  Get-DeviceCollection | ./my-script.ps1
  
  # By hashtable with id property (using positional argument)
  ./my-script.ps1 @{id="12345"}, @{id="6789"}

  Now let's say that you wanted to add some logic which required the full device managed object from the server, and not just the id and name fields. This can be achieved by adding the -Fetch parameter to the Expand-Device cmdlet call.

  The differences in the output can be shown in the small example

  # This will not fetch the device (as the device already exists)
  PS> 1234 | Expand-Device
  
  id   name
  ---- ----
  1234 [id=1234]

  Agent but using -Fetch.

  # Using -Fetch will return the whole device managed object from Cumulocity (1 x GET request)
  PS> 1234 | Expand-Device -Fetch
  
  additionParents : @{references=System.Object[]; self=https://example.cumulocity.com/inventory/managedObjects/1234/additionParents}
  assetParents    : @{references=System.Object[]; self=https://example.cumulocity.com/inventory/managedObjects/1234/assetParents}
  c8y_IsDevice    : 
  childAdditions  : @{references=System.Object[]; self=https://example.cumulocity.com/inventory/managedObjects/1234/childAdditions}
  childAssets     : @{references=System.Object[]; self=https://example.cumulocity.com/inventory/managedObjects/1234/childAssets}
  childDevices    : @{references=System.Object[]; self=https://example.cumulocity.com/inventory/managedObjects/1234/childDevices}
  creationTime    : 1/19/2021 7:49:33 PM
  deviceParents   : @{references=System.Object[]; self=https://example.cumulocity.com/inventory/managedObjects/1234/deviceParents}
  id              : 1234
  lastUpdated     : 1/19/2021 8:52:29 PM
  name            : mynewname
  owner           : user@example.com
  self            : https://example.cumulocity.com/inventory/managedObjects/3882

New Features

• Added commands to manage managed object child additions

  PowerShell

  • Get-ChildAdditionCollection
  • New-ChildAddition
  • Remove-ChildAddition

  Bash/zsh

  • c8y inventoryReferences listChildAdditions
  • c8y inventoryReferences createChildAddition
  • c8y inventoryReferences deleteChildAddition

Performance improvements

• Reduced number of API calls within PSc8y and c8y binary by skipping lookups when an ID is given by the user. Previously PSc8y and c8y were sending two API calls to the server in order to normalize the request by retrieving additional information and potentiall shown to the user. Since this is currently not used, it has been removed.

Bug fixes

• Set-Session no longer causes the terminal bell/chime when using backspace or arrow keys.

Bug fixes

Bug fixes

• Get-C8ySessionProperty selects first matching Session parameter in the call stack if multiple matches are found

Bulk Operation commands and improved support for custom powershell functions

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

v1.8.0

Features

• Added -ProcessingMode parameter to all commands that use DELETE, PUT and POST requests.

  Bash/zsh

  c8y inventory create --name myobject --processingMode TRANSIENT

  PowerShell

  New-ManagedObject -Name myobject -ProcessingMode TRANSIENT
  New-ManagedObject -Name myobject -ProcessingMode QUIESCENT
  New-ManagedObject -Name myobject -ProcessingMode PERSISTENT
  New-ManagedObject -Name myobject -ProcessingMode CEP

• Added logout user command to invalidate current user token

  Bash/zsh

  c8y users logout

  PowerShell

  Invoke-UserLogout

Minor improvements

• Expand-Device supports piping of alarms, events, measurements and operations

• Set-session automatically selects a session if only one matching session is found rather than prompting the user for the selection

• source fragment is removed when being passed via file to the Data parameter in all create and update commands

  // myevent.json
  {
      "source": {
          "id": "99999",
          "self": "https:/..../event/events/99999"
      },
      "type": "myExample1",
  
  }

  When executing the following command:

  PSc8y\New-Event -Device 12345 -Data myevent.json

  The source id fragment will be replaced entirely by the new source as specified by the Device parameter

  // myevent.json
  {
      "source": {
          "id": "12345",
      },
      "type": "myExample1",
  
  }

Bug fixes

• Get-Session uses a new c8y session get to retrieve information about the current session
• Fixed bug when using the -Session on PUT and POST commands which resulted in an error being displayed even though the request would be successful
• Fixed binary upload bugs with both New-EventBinary and Update-EventBinary which resulted in multipart form data being included in the binary information

Two-factor-authentication (TOTP) and session encryption

• New-Microservice requiredRoles are now set when passing the cumulocity.json manifest file to the -File parameter

• Added New-ServiceUser and Get-ServiceUser to create and get a service user that can be used for automation purposes

  New-ServiceUser -Name "myapp1" -Roles "ROLE_INVENTORY_READ" -Tenants "t12345"
  
  Get-Serviceuser -Name "myapp1"

• Fixed target tenant confirmation when using the -Session parameter on PUT/POST commands

• Invoke-ClientRequest: Added support for -Template and -TemplateVars parameters

• Removed -Depth from internal ConvertFrom-Json calls so that the PSc8y is compatible with PowerShell 5.1

• Fixed shallow json conversion bug when using using internal calls to ConvertFrom-Json and ConvertTo-Json. Max depth of 100 is used on supported PowerShell versions

• Test-ClientPassphrase cmdlet to check if passphrase is missing or not. Cmdlet is called automatically when importing the module or calling set-session

• New-User added support for template and templateVars parameters

• Dry/WhatIf headers are shown in a sorted alphabetically by header name

• Added Two-Factor-Authentication support

  • TOTP (only)

• Added OAUTH_INTERNAL support

• Encrypting sensitive session information

  {
      "credential": {
          "cookies": {
              "0": "{encrypted}abefabefabefabefabefabefabefabefabefabef",
              "1": "{encrypted}abefabefabefabefabefabefabefabefabefabef",
          }
      },
      "password": "{encrypted}abefabefabefabefabefabefabefabefabefabef"
  }

• Added encrypt/decrypt commands

  $encryptedText=$( c8y sessions encryptText --text "Hello World" )
  
  c8y sessions decryptText --text "$encryptedText"

• Fixed broken doc link