PowerShell Connector Failed Operations
If an operation against the target system fails, the PowerShell script must handle this correctly so that UNIFYBroker can correctly generate accurate logging and reporting.
Complete Failures
If an operation being handled by a PowerShell script fails completely, the exception can either be left to be handled by UNIFYBroker, which will report the error back; alternatively it can be retried in the PowerShell script.
Single Operation Failures
Where many singular operations are being applied to one or more entities, such as Adds, Deletes or Updates, failure can be reported on a per-entity basis.
UNIFYBroker makes available Failures, an empty collection which should be populated with entities that do not successfully complete the operation against the target system:
foreach ($entity in $components.InputEntities)
{
# Perform an operation
$boolIsSuccessful = ...
if ($boolIsSuccessful -eq $false)
{
$components.Failures.Push($entity)
}
}
Customer support service by UserEcho
Some additional observations on error handling in PowerShell scripts for IdB:
1. Always set $ErrorActionPreference = "Stop". If you have it set to "Continue" then IdB cannot report on individual errors associated with this entity and instead lists all the errors encountered (which can include errors that have nothing to do with that entity). Setting a "Stop" value does not mean IdB will stop everything on the first error, and conversely setting a "Continue" value won't force IdB to continue in certain conditions - so it's best to just use "Stop".
2. Always use try-catch and other error handling techniques in Import scripts. I have found that if errors are not handled in import scripts it can prevent the entire import running, even if the error only affected one entity.
3. Conversely, be careful with the use of try-catch in Export scripts, and if you do use it, make sure to log and push all errors to IdB. A simple yet effective approach is to not catch the errors at all but just let the Export script fail - it only impacts the failed entity export (other successful ones will still go out), IdB reports an export failure back to MIM, and the actual message is in the IdB log.
Carol's advice is still valid in 2021, with one note. In UNIFYBroker/Plus an export script which throws an exception will cause all updated/added entities to be left untouched in the adapter even if some succeeded. Sometimes I've seen phantom joins left behind which cause later errors in the case of Add operations and thereafter require the Locker to be cleared and re-baselined. Regardless, all updates/adds will be retried at a future time when the next Baseline is run, which can cause other problems (especially if import operations haven't run in the meantime to pull in the updates/adds that were successful). I suggest always using try/catch and $components.Failures.Push() in all export scripts.