TL;DR:

1. Is this approach sane?
2. How do we trap Tridion Docs-specific errors, like -109, in PowerShell?
3. Is Set-IshUser the correct way to update an existing user?

Hi! This is probably a pretty basic question, but, well, I'm still new to PowerShell and stuck. We've already logged in and created an IshSession. We import a CSV list containing the metadata describing internal users to create or update. Its columns (e.g. NewUserEmail) are named to match my PowerShell variable names ($NewUserEmail):

### Begin import ###

import-csv $ImportFile | foreach {

#Yes, this is redundant, but it might be helpful at some point later,
#and it's easier to read and type once assigned to a regular variable.
$NewUserDisplayName = $_.NewUserDisplayName#+(Get-Date).ToString("yyyyMMddHHmmssfff") #Tags each name down to the millisecond (fff) to make them unique so we don't have to keep erasing the users every time we re-run this.
$NewUserEmail = $_.NewUserEmail
$NewUserLanguage = $_.NewUserLanguage
$NewUserPassword = $_.NewUserPassword
$NewUserUserGroups = $_.NewUserUserGroups
$NewUserUserRoles = $_.NewUserUserRoles
$NewUserUserType = $_.NewUserUserType

#Build metadata

$NewUserMetadata=
Set-IshMetadataField -IshSession $ishSession -Name "FISHUSERDISPLAYNAME" -value $NewUserDisplayName |
Set-IshMetadataField -IshSession $ishSession -Name "FISHEMAIL" -value $NewUserEmail |
Set-IshMetadataField -IshSession $ishSession -Name "FISHUSERLANGUAGE" -value $NewUserLanguage |
Set-IshMetadataField -IshSession $ishSession -Name "PASSWORD" -value $NewUserPassword |
Set-IshMetadataField -IshSession $ishSession -Name "FUSERGROUP" -value $NewUserUserGroups |
Set-IshMetadataField -IshSession $ishSession -Name "FISHUSERROLES" -value $NewUserUserRoles |
Set-IshMetadataField -IshSession $ishSession -Name "FISHUSERTYPE" -ValueType Element -Value $NewUserUserType

#Create the internal user. If Add-IshUser fails with "error 109;ObjectAlreadyExist", update the user.

Try {
$ishAddUserObject = Add-IshUser -IshSession $ishSession -Name $NewUserDisplayName -Metadata $NewUserMetadata
$FinalStateVerb = "creating"
$BackgroundColor = "Green"
}
Catch [ObjectAlreadyExist] {
Write-Host $NewUserDisplayName "already exists. We should update, not create."
$FinalStateVerb = "updating"
$BackgroundColor = "Green"
}
Catch {
Write-Host "Something unexpected happened:" -ForegroundColor White -BackgroundColor Red
Write-Host "Error record stored in the current object variable:" $_
Write-Host "Exception.Message:" $_.Exception.Message
Write-Host "Exception.ItemName:" $_.Exception.ItemName
$FinalStateVerb = "fighting"
$BackgroundColor = "Red"
}
Finally {
Write-Host "OK, we're done $FinalStateVerb $NewUserDisplayName" -ForegroundColor White -BackgroundColor $BackgroundColor
}

#Confirm the user exists
Write-Host Confirming $NewUserDisplayName
Test-IshSession -WsBaseUrl $ishWsBaseURL -IshUserName $NewUserDisplayName -IshPassword $NewUserPassword #Expected outcome if user exists: True

}

Without the Try/Catch/Finally block (i.e. just Add-IshUser and no error handling), new users are created, but for existing users we get this error and nothing happens to them:

Presumably we use Set-IshUser to update existing users, but we need to set up an if...then condition. Google tells me the cool PowerShell kids use Try/Catch/Finally, so I added the coloured blocks in the sample code. We now get:

Something is clearly happening. We see Finally's "we're done" message followed by the clear failure of my condition in the first Catch. (Umm... what's with that order?)

I've experimented with various things in the square brackets, but clearly don't understand the point. (Something to do with 'type'.)

1. Is this approach sane?
2. How do we trap Tridion Docs-specific errors, like -109, in PowerShell?
3. Is Set-IshUser the correct way to update an existing user?

BTW examples like this from Naoki Hirai: https://community.sdl.com/product-groups/tridion/tridion-docs/f/forum/33736/updating-object-s-metadata-using-content-importer appear to have only one possible error, so the Catch block doesn't have to evaluate anything; it just responds to that error. I'd like evaluation so I can branch my actions.

Thanks!

Neman