We'll focus here on the use of Application Composer, however for applications outside of Sales/CRM it should be noted that options also exist through the tailoring of the standard texts used in existing messages through either the UI Text customization feature and the Manage Messages task available in Setup and Maintenance.
Validation Messages
When you add custom validation logic to a field (on tabbing out) the usability recommendation is to use a mode-less type message. There are two supported ways of doing this in Application Composer; a warning message or an error message. They both prevent the transaction from being submitted, however the error-type also creates a pop-up on the submit also.
These are available for both standard and custom objects, within the Server Scripts functionality, and under the Validation Rules tab. The error message text must be explicitly created in the field on the rule creation page. By default if the groovy logic in the rule returns false then the message specified will be shown as an error-type message, however you can also include implicit calls to the following to generate the error or warning (note: at this time there is no support to pass additional parameters in these calls).
adf.error.raise(null)adf.error.warn(null)
The following video provides a simple demonstration.
In addition, if your validation needs to highlight a field on the page that is not the one you have written the rule against (e.g. you're using a hidden field), then you can also use the following call and it will shows the message specified upon submit.
adf.error.addAttribute('FieldName')Validation Exceptions
If you need something more obvious that resembles a standard modal pop-up dialog, then you can include the following in your Groovy code logic anywhere in a script. This would commonly be used in a Trigger rather than a Rule.
throw new oracle.jbo.ValidationException('Your Custom Message Here') This is the recommended way of providing custom script feedback to users via a pop-up message, and an enhancement request (17191577) is open for an API for informational type messages.
Using this Validation Exception also allows you to build your text string at run-time based on the exact problem encountered. As an example, your dynamic message text could account for a users locale, providing the appropriate translation. It should be noted that there is no access to resource bundles within raising exceptions at this time.
JBO Messages
It is also possible to raise exceptions in the underlying ADF framework directly from Groovy. This is not the recommended way to display messages to users, however is intended for use when your code is performing a complex operation and you need to catch the full details for later debugging. Similar to above, this is either via a more critical JboException object or a less severe JboWarning object. Both of these classes have a range of methods you can use to retrieve more details:
- getMessage()
- getDetails()
- getErrorCode()
- getErrorParameters()
- getLocalizedMessage()
These would be used in combination with the Runtime Messages feature inside Application Composer, as demonstrated in this video. The following simple code snippet illustrates how you would catch the error, check its type, and use details to output to the logger.
try{ ...your code... }catch(e) {println("Exception = " + e.getMessage())if(e instanceof oracle.jbo.JboException){if(e.getDetails() != null){for(Object detailEx: e.getDetails()){println("Detail exception:")println(detailEx.getMessage())}}}}