UcmPsTools Cmdlet Status Reporting
Most of the functions in this module will return a PSCustomObject on the pipeline indicating the success or failure of each function and some descriptive text along with it.
Detailed descriptions of the output of each function can be found in the comment-based help in each function.
Always check the documentation for the cmdlet you are working with to understand its specific messages and how to handle them.
Understanding The Returned Object
$Return.Status usually returns one of four values. "OK": The operation was successful, nothing of concern "Warning": The intent of the operation was successful, but there is something you should be mindful of. (Eg, We are trying to create a user that already exists, or we are running low on licences to assign). More information will be found in $Return.Message "Error": The operation was unsuccessful, Something happened when attempting to perform the operation that we couldn't handle, check $Return.Message for more information "Unknown": Cmdlet reached the end of the function without returning anything, this shouldn't happen, if it does please log an issue on GitHub with your relevant log files.
$Return.Message will typically return descriptive text relevant to the status, for example If Return.Status is "OK" when creating a user, $Return.Message will contain the user ID. if however Return.Status is "Warn" $Return.Message will include information as to why we generated a warning. IE "Number Already assigned to [email protected]" Should Return.Status equal "Error" $Return.Message will either be a descriptive text of the issue or the raw error message produced by a sub cmdlet.
Presently each cmdlet only supports one object and thus only returns one object. This may change in future, thus in future builds, you may have multiple objects returned if you send multiple objects on the pipeline!
Examples
OK
Grant-UcmOffice365UserLicence successfully assigns the Flow Free licence to user [email protected]
PS> $foo = (Grant-UcmOffice365UserLicence -UPN [email protected] -LicenceType Flow_Free -Country AU)
##Log Messages Generated by Cmdlet
INFO: Verifying Flow_Free is available
INFO: Checking for existing User [email protected] ...
INFO: User exists. checking their assigned licences...
INFO: User Exists, Grant Licence
INFO: Setting Location
INFO: Licence Granted
PS> $foo
##Returned object on the Pipeline
Name Value
---- -----
Function Grant-UcmOffice365UserLicence
Status OK
Message Licence Granted
Warning
Grant-UcmOffice365UserLicence attempted to assign a licence to [email protected] 2 warnings were encountered. - The available licence count is low (<5%) - The user already has that licence
PS> $foo = (Grant-UcmOffice365UserLicence -UPN [email protected] -LicenceType MCOPSTNEAU2 -Country AU)
##Log Messages Generated by Cmdlet
INFO: Verifying MCOPSTNEAU2 is available
WARNING: 15:22:47 Only 5 MCOPSTNEAU2 Licences Left
WARNING: 15:22:47 Available licence count low...
INFO: Checking for existing User [email protected] ...
INFO: User exists. checking their assigned licences...
WARNING: 15:22:48 User already has that licence, Skipping
PS> $foo
##Returned object on the Pipeline
Name Value
---- -----
Function Grant-UcmOffice365UserLicence
Status Warning
Message Skipped: Already Licenced, Warning Message Low Licence Count
Error
Grant-UcmOffice365UserLicence is called to assign a licence that doesn't exist, which is reported with an error
PS> $foo = (Grant-UcmOffice365UserLicence -UPN [email protected] -LicenceType TCO -Country AU)
##Log Messages Generated by Cmdlet
INFO: Verifying TCO is available
WARNING: 15:00:02 Unable to locate the requested licence on the current tenant
PS> $foo
##Returned object on the Pipeline
Name Value
---- -----
Function Grant-UcmOffice365UserLicence
Status Error
Message Unable to locate TCO licence Grant-UcmOffice365UserLicence is called to assign a licence to a user that doesn't exist, which is reported with an error.
PS> $foo = (Grant-UcmOffice365UserLicence -UPN [email protected] -LicenceType MCOPSTNEAU2 -Country AU)
##Log Messages Generated by Cmdlet
INFO: Verifying MCOPSTNEAU2 is available
WARNING: 15:08:11 Only 5 MCOPSTNEAU2 Licences Left
WARNING: 15:08:11 Available licence count low...
INFO: Checking for existing User [email protected] ...
WARNING: 15:08:11 Something went wrong granting [email protected]'s licence
INFO: Could not locate user [email protected]
PS> $foo
##Returned object on the Pipeline
Name Value
---- -----
Function Grant-UcmOffice365UserLicence
Status Error
Message User Not Found
Whilst I do my best to keep messages consistent. I may change specific wording over time. $_.Message is the human-readable result whilst the $_.Status attribute should be considered as your pass/fail metric.
Last updated