How to handle errors with powerPLM (powerFLC) cmdlets

The powerFLC cmdlets provide a way to retrieve the error and its message when encountering a problem during execution. This can be useful when debugging a script which is using the powerFLC cmdlets. The behavior is documented on the respective page for the cmdlet in the coolOrange documentation.

Most of the powerFLC cmdlets make use of the automatic variable $Error build into powerShell to make errors accessible to the user. By default the error will be written to the $Error variable but the cmdlet will not throw the error directly. This means that, in case the following would run into an error it would return no result but would finish executing:

$result = Get-FLCItems -Workspace 'No workspace with this name exists'

Checking the content of the $Error[0] variable would print the last error the cmdlet encountered e.g. :

PS C:\Users\coolOrange> $Error[0]
Get-FLCItems : No Workspace found with the given name: No workspace with this name exists
At line:1 char:11
+ $result = Get-FLCItems -Workspace 'No workspace with this name exists ...
+           ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : NotSpecified: (FLC.Cmdlets.Cmdlets.GetFlcItems:GetFlcItems) [Get-FLCItems], Exception
    + FullyQualifiedErrorId : FLC.Cmdlets.Cmdlets.GetFlcItems

To retrieve only the error message itself to present it for example to an end user the Message property can be used:

$Error[0].Exception.Message

With the common parameter -ErrorAction you can control how the cmdlet behaves when an error occurs during execution. The default value when not set for the cmdlet is SilentlyContinue which continues executing the command on error.

In some case it might be useful to set the -ErrorAction to Stop which displays the error message and stops executing the command:

$result = Get-FLCItems -Workspace 'No workspace with this name exists' -ErrorAction Stop

Get-FLCItems : No Workspace found with the given name: No workspace with this name exists
At line:1 char:11
....

Connect-FLC

Error messages for the Connect-FLC cmdlet behave differently than other powerFLC cmdlets. They are returned together with the result and can be retrieved by using the Error property of the $result:

$result = Connect-FLC -Tenant 'your_tenant_name' -ClientId 'your_client_id' -ClientSecret 'your_client_secret' -UserId 'your_email@example.com'
 
if(-not $result) {
   $result.Error #Returns "Authentication to Forge failed!"
}