Best Practices for IDM 3.5 Form Script
Novell Cool Solutions: Feature
By Rudy Duym

Posted: 5 Jul 2007

This article describes some of the best practices on how to use and organize the form script in IDM 3.5 workflows.

BP #1: Data Validation#

There are a number of places where you can script data validation:

  • In the onchange event of the control itself
  • Attaching a function to the control's build-in validate function
  • Attaching a function to one of the submit actions

Which is the best place? It really depends on the validation that must be done, and whether other fields are involved in the validation.

Data validation in the onchange event

Using the onchange event can be tricky, because it is also fired when the control is loaded. This is done to allow synchronization between this field and others. Triggering the onchange event in each control, once all controls have been loaded, allows for easy synchronization between those controls that have dynamic content. So in a general way, the onchange event should only be used to do validations that only concern the field itself. Always make sure you consider the initial onchange that is fired on form load; otherwise, you might be showing an error complaining about an empty or invalid field as soon as the form has finished loading!

Data validation by extending the build-in validate function

This is the best place, in my opinion, for atomic data validation - where you do not need other fields' values to validate the current control's data. See the form.addCustomValidation() examples in this article.

Data validation by attaching a function to a submit button

This is the best place, in my opinion, for compound data validation - where you need to validate a block of field values in one pass, such as in an address (street, number, zip, town, state) or a credit card.

You can even add an extra button to your form that will allow the user to validate the data without using one of the Submit buttons.

BP #2: Organizing Your Scripts#

When starting to write form scripts, it is natural to start out with form scripts written directly in the build-in or custom events.

A more modular approach is to write re-usable functions that will be stored in an internal script, and then call them from within the events. If you need to have access to the predefined form and IDVault objects inside your functions, you must pass them as parameters to your functions when calling the functions from one of the events.

If you want to re-use some of your functions in more than one form, you must create a library, store your functions there, and include them with an external script reference in your form (this is not working right now; see the workaround in the Known Issues). This library can be added to the UA's WAR in the Javascript folder, but it is better practice to add them to a WAR of your own inside Jboss's deployment folder. You can simply reference the library with a relative URL, the starting position being the request or approval jsp inside the UA.

Example: If you add a library called mylib.js to a war called myscripts.war to the deployment folder of Jboss, you can access it with this relative URL: ?../../myscripts/mylib.js? from within a workflow form.

BP #3: Internationalization and Localization#

You can use java resourcebundles when showing errors or other information to the user. The form.showMsg(), showWarnign(), showError(), and showFatal accept a key and bundle ID. The resourcebundle must be on the Jboss's classpath, either in the UA WAR or in JBoss's lib folder.

You can also directly extract an entry from a resourcebundle with form.getRBMessage.(). Should you need to test the user's locale, it is available from form.getLocale().

More Information#

There might be more information for this subject on one of the following: