Error Handling

All output, including errors, are captured in the script’s “Additional Information” field for each execution result where each line represents output from the script. In the event of a error, the script will return a non-zero exit code and the last unhandled exception message will be returned. For end users, this will typically manifest as an error message on the form they’re trying to save. If no error message is present but the executed script resulted in an error, a general message to the end user will indicate that the results of a script are preventing them from saving their form.

Custom Error Messages

You can provide custom error messages to your end users by using PowerShell’s Write-Error cmdlet. This command will write an error message to the output stream and automatically place the script into an error state that causes it to return exit code -1.

in scripts that perform some kind of validation, it’s useful to have meaningful error messages that clearly convey an issue to help guide them towards successfully completing their form. For example, you may have a business requirement that your client reference field must be at least 6 characters long. You could have a script like the following to enforce this requirement:

# This script has a "Before Save" event trigger on the "Client" object

$incomingClient = Get-InboundObjectInstance

if (($null -eq $incomingClient.Reference) -or ($incomingClient.Reference.Length -lt 6)) {
    Write-Error "The reference field must be at least 6 characters long"
    exit
}

return $incomingClient

Note that if the validation logic fails in this example, the script uses the Write-Error cmdlet and exits the script to place the script into an error state and prevent further actions within the script. When a user encounters this error, the error message will be shown at the bottom of their client form like the following: