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 example@contoso.com" 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.
As each cmdlet has different messages depending on its function, Check the cmdlet's comment-based help or the cmdlet documentation
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 discord@contoso.com.au
Warning
Grant-UcmOffice365UserLicence attempted to assign a licence to discord@contoso.com.au 2 warnings were encountered. - The available licence count is low (<5%) - The user already has that licence
Error
Grant-UcmOffice365UserLicence is called to assign a licence that doesn't exist, which is reported with an error
Grant-UcmOffice365UserLicence is called to assign a licence to a user that doesn't exist, which is reported with an error.
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