This section includes information on the following topics:
Unlike the ECMAScript that runs in other components of the workflow, form script executes on the Web browser, not the server. All directory access from within form script is handled by AJAX calls from the browser to the server.
This section lists all form action methods and properties supported by the ECMA Expression Builder.
Lets you work with Form methods.
form.focus(fieldname)
Sets the focus to the specified field. For list-based or choice-based controls, sets the focus to either the selected choice or when no selection is made, it sets the focus to the first choice. If a fieldname parameter is passed and that field is list or choice based, it sets the focus on the choices corresponding to the values parameter. If the value is an array, only the first value is used to determine on which check box or radio button to set focus. If the specified field is invisible or disabled, this method has no effect.
form.select(fieldname)
If no values parameter is passed in, this method sets the focus to the underlying text field. For list-based or choice-based controls, this method sets the focus to the selected choice or if no selection was made, to the first choice. If a values parameter is passed and the field is list-based or choice-based it sets the focus on the choices corresponding to the fieldname parameter. This method has no effect on disabled or invisible fields.
form.activate(fieldname)
A combination of setFocus() and select().
form.setRequired("fieldname", is-required)
Sets the field to required if is-required is True; otherwise, the field is optional. A field that is required blocks the form submission if the field is empty.
form.interceptAction("actionname", "order", "function")
Allows you to intercept the script attached to an action button. The function passed in is executed based on the order parameter.
Valid actionname values are SubmitAction and CancelAction.
The choices for actionname for an approval form are: ApprovalAction, RefusalAction, DenyAction, UpdateAction, CancelAction and CommentAction.Valid values for the advice parameter are:Before: The function is called before the script attached to the button executes.after: The function is called after the script attached to the button executes.around: The function is passed a parameter that allows you to decide whether to execute the script attached to the button The following example shows the submit action intercepted. The form is only submitted if the user replies Yes.
window.inv=function (invocation) { if (confirm( "Are you sure you want to submit ?")) { var result = invocation.proceed(); return result; }; };
form.interceptAction("SubmitAction", "around", window.inv);
form.getLocale()
Returns the current locale. Can be used as input for all methods that support a locale parameter.
form.getRBMessage(key)
form.getRBMessage(key, value[s])
form.getRBMessage(key, value[s], bundle)
This method tries to find an entry with key in the resource bundle with ID bId. The resourcebundle Java class should extend the java.util.ListResourceBundle.Parameter. The parameter can be used to pass in replacements for parameters ({0}, {1}, etc) in message "msg"; for example:
var msg = frm.getRBMessage ("mykey", ["value0", "value1"], "mybundle");
form.stringToDate(date)
form.stringToDate(date, include-time)
Converts a date string to a Date. The format must correspond to the dateform for the current locale, as used in the DatePicker. The value of a DatePicker control can be converted with this method. Example:
form.showMsg("Date="+form.stringToDate(d,true));
form.dateToString(date)
form.dateToString(date, include-time)
Converts a date to a string that can be stored in the DatePicker, for example:
var d = form.dateToString(new Date(), true);
form.setValues("hireDate", d);
form.isValidDate(date)
Use this to validate the correct format for a date string.
form.isValidDate(date, include-time)
Use this to validate the correct format for a date string.
form.alert("msg")
Displays a message in an alert box.
form.showMsg(msg, param, bId)
Adds a message to the status portion of the form. The msg string parameter can either contain the text of the message itself or it can contain a key pointing to an entry in the resource bundle bId. This method always tries to find an entry with the key msg in the resource bundle with the id bId.The param parameter can be used to pass in replacements for stakeholders ({0}, {1}, etc) in msg.
NOTE:If you want to add debugging messages to your script, it is better practice to use form.showDebugMsg().
Example:
form.showMsg("my message" {0},{1}", ["value0","value1"]);
form.showWarning(msg, param, bId)
Adds a warning to the status portion of the form.
The msg string parameter can either contain the text of the warning itself or it can contain a key pointing to an entry in the resource bundle bId. This method always tries to find an entry with the key msg in the resource bundle with the id bId. The param parameter can be used to pass in replacements for stakeholders ({0}, {1}, etc) in msg.
NOTE:If you want to add debugging messages to your script, it is better practice to use form.showDebugMsg() .
Example:
form.showWarning("my warning" {0},{1}", ["value0","value1"]);
showError(msg, param, bId);
Adds an error message to the status portion of the form.
The msg string parameter can either contain the text of the error itself or it can contain a key pointing to an entry in the resource bundle bId. This method always tries to find an entry with the key msg in the resource bundle with the id bId. The param parameter can be used to pass in replacements for stakeholders ({0}, {1}, etc) in msg.
NOTE:If you want to add debugging messages to your script, it is better practice to use form.showDebugMsg() .
Both normal and fatal errors block form submission. The distinction between a normal error and a fatal error is that normal errors get reset just before form validation occurs (because of a form submission). Fatal errors are remembered and therefore block the form submission unless you restart. A normal error only blocks submission if it is generated during the validation phase. If you add normal errors during onload or custom events, they are lost when the form is submitted.
NOTE:If you want to add debugging messages to your script, it is better practice to use form.showDebugMsg().
Example:
form.showError("my error" {0},{1}", ["value0","value1"]);
form.showFatal("my fatal" {0},{1}", ["value0","value1"]);
Adds a fatal error message to the status portion of the form.
The msg string parameter can either contain the text of the fatal error itself or it can contain a key pointing to an entry in the resource bundle bId. This method always tries to find an entry with the key msg in the resource bundle with the id bId. The param parameter can be used to pass in replacements for stakeholders ({0}, {1}, etc) in msg.
Both normal and fatal errors block form submission. The distinction between a normal error and a fatal error is that normal errors get reset just before form validation occurs (because of a form submission). Fatal errors are remembered and therefore block the form submission unless you restart. A normal error only blocks submission if it is generated during the validation phase. If you add normal errors during onload or custom events, they are lost when the form is submitted.
NOTE:If you want to add debugging messages to your script, it is better practice to use form.showDebugMsg().
Example:
form.showFatal("my fatal" {0},{1}", ["value0","value1"]);
form.enable("fieldname")
Enables a field on a form.
form.disable("fieldname")
Disables a field on a form.
NOTE:A disabled field still sends data back to the workflow engine. The content of a disabled field is validated when submitting the form or when calling the field.validate() method.
form.getValue("fieldname")
Returns the first value for the field. The type returned is always string, independent of the data type of the field. If the field does not have a value, the method returns an empty string if text can be entered into the field (like Text, TextArea, DatePicker, DNLookup) or it returns “undefined” if the control is choice-based (for example, StaticList, radio buttons, check boxes). For DN type controls, this method always returns the DN and never the display expression.
form.getValues("fieldname")
Returns a string array containing the values. If no values are found, the array is empty (size = 0). For DN type controls, this method always returns the DN and never the display expression.
form.setValues("fieldname", data-values, display values, KeepOldValues)
Sets a value. Supports multiple values. This method allows changing the available entries for list-based controls (for example, StaticList, MVCheckbox, PickList). By default, existing values are deleted unless the KeepOldValues parameter equals True. For non-list-based controls, the display values parameter is ignored.
Lets you work with Field methods.
field.activate(value[s])
This method is a combination of field.focus() and field.select().
field.disable()
Disable the field.
NOTE:A disabled field still sends data back to the workflow engine. The content of a disabled field is validated when submitting the form or when calling the field.
field.enable()
Enable the field.
field.fireEvent("eventname")
Fires a custom event. Passes the name of the custom event that is fired. To get the values of the event that is fired, use form.getValues(event.getOrigin()).
field.focus(value[s])
If no values parameter is passed in, this method sets the focus to the underlying text field. For list-based or choice-based controls, this method sets the focus to the selected choice if no selection was done to the first choice. If a values parameter is passed and if the field is list-based or choice-based, this method sets the focus on the choices corresponding to the values parameter. If the values parameter is an array, only the first value is used to determine the check box or radio button to set focus. This method has no effect on disabled or invisible fields.
field.getLabel()
Gets the label associated with the field. If no label is found, this method returns the name of the field.
field.getName()
Gets the name of the field.
field.getValue()
Returns the first value for the field. The type returned is always a string, independent of the data type of the field. If the field does not have a value, the method returns an empty string if text can be entered into the field (like Text, TextArea, DatePicker, DNLookup) or it returns “undefined” if the control is choice-based (for example, StaticList, radio buttons, check boxes). For DN type controls, this method always returns the DN and never the display expression.
field.hide()
Hides this field.
form.getValues()
Returns a string array containing the requested values. If no values are found, the array is empty (size = 0). For DN type controls, this method always returns the DN and never the display expression.
field.show()
Shows this field.
field.select(value[s])
If no values parameter is passed in, this method sets the focus to the underlying text field. For list-based or choice-based controls, it sets the focus to either the selected choice or if no selection was made, it sets the focus to the first choice. If a values parameter is passed and if the field is list-based or choice-based, it sets the focus on the choices corresponding to the values parameter. If the value parameter is an array, only the first value is used to determine which check box or radio button to set focus on. This method has no effect on disabled or invisible fields.
field.setRequired(is-required)
Sets the field to required if isRequired is True or optional otherwise. A field that is required blocks the form submission if it is empty.
field.setValues(data-values, display-values, KeepOldValues)
Sets a value. Supports multiple values. This method allows changing the available entries for list-based controls (for example, StaticList, MVCheckbox, PickList). By default, existing values are deleted unless the KeepOldValues parameter equals True. For non-list-based controls, the display values parameter is ignored.
If you want to set or change the initial value of a field, you should do so in an onload event.
NOTE:This method triggers the onchange event for the field.
Examples:
field.setValues("cn=jdoe,ou=users,ou=mysample,o=novell"); // for a DNLookup
field.setValues(["jdoe@novell.com", "test@novell.com"]) // for an MVEditor
field.setValues(["W","B"],["White","Black"],true); // for a StaticList
field.validate()
Triggers browser validation for the field. To validate the data entered in this field as soon as the user navigates to another field, call this method in the onchange event. Returns True if validation errors were detected; otherwise, returns False..
Lets you work with events. This section includes the following methods:
event.getEventName()
Returns the name of the event.
event.getOrigin()
Returns the name of the field from which the event was triggered.
event.getValue()
Returns a string that contains the first value in the event.
You should not use the value that is returned by this method, because it is possible that a user might have modified the data in the field after the event was triggered. Instead, you should use the value returned by the form.getValue method. For example, form.getValue(event.GetOrigin()). This ensures that you get the current value of the field. If you select event.getValue() from the pick list in the ECMA Expression Builder, form.getValue(event.GetOrigin()) is inserted.
event.getValues()
Returns an array of strings that contains all values in the event.
You should not use the value that is returned by this method, because it is possible that a user might have modified the data in the field since the event was triggered. Instead, you should use the value returned by the form.getValues method. For example, form.getValue(event.GetOrigin()). This ensures that you get the current value of the field. If you select event.getValues() from the pick list in the ECMA Expression Builder, form.getValues(event.GetOrigin()) is inserted.
Lets you work with lists.
IDVault.globalList("fieldname", "key", "locale")
Retrieves a global list from the directory abstraction layer, identified by the key of the global list. If the field name is specified, the result of the query is used to refresh the content of the field. To retrieve a list without storing the result in a field, use a null value for the fieldname parameter.The locale is optional. If locale is not specified, the locale in the HTTP request is used.
Example:
IDVault.globalList("dallist", "departments", "en");
Lets you work with queries.
globalQuery(fieldname, key, param)
Executes the predefined directory abstraction layer query key (see Queries General Properties). If the field name is specified, the result of the query is used to refresh the content of the field. To retrieve a list without storing the result in a field, use a null value for the fieldname parameter.The param parameter is used as input to the query. The parameter has the form {parname1:value,parname2:value}, in which the value can be an individual value or an array. The first column of the result list (always a DN) is used for the data value, and the second column is used for the display label.
Example:
IDVault.globalQuery("canchangepwd", "getsites"); // query without a parameter
IDVault.globalQuery("building", "getbuildings", {site:form.getValue("site")}); // query with one parameter
IDVault.globalQuery("room", "getrooms", {site:form.getValue("site"), building:form.getValue("building")}); // query with two parameters
Lets you work with containers.
IDVault.containers("test", rootdn, SearchScope, ShowDN)
Gets a list of containers, with the scope equal to “subtree” or the same level. The method returns an array with two entries, the first an array with the resulting DNs; the second entry an array with the display labels.
Table 9-5 Container Parameters
Example:
IDVault.containers("assetProp2", null, "o", true); // set the entries in a StaticList to all containers directly under the root DN of the default entity
This section lists functions that are used with IDVault data.
DNcompare(String dn1, String dn2)
Performs a case-insensitive comparison of DNs from the Identity Vault. Returns True if the DNs are the same.
A DN encapsulates a distinguished name (an LDAP name with context). The syntax of the DNs must conform to that specified in RFC 2253, which describes the String representation of DNs. The following DNs are all valid for use with DNCompare (and would return True if compared):
cn=jdoe,ou=users,ou=idmsample,o=acme CN=jdoe,ou=users,ou=idmsample,o=acme cn=JDOE,ou=users,ou=idmsample,o=acme
For more information about RFC 2253, see RFC 2353.
Example:
if ( IDVault.DNcompare(flowdata.get('Activity3/CardRequest/Candidate'),recipient )) true; else false ;
get()
get(fieldname)
get(fieldname,dn)
get(fieldname,dn,entity-type)
get(fieldname,dn,entity-type,attribute)
This corresponds to the IDVault.get() function of the workflow script engine. Retrieves the values of the attribute for the given entity. The result is an array of values. If the field parameter is specified the result of the query result is used to refresh the content of the field. If not, the result is up to the form developer to use the result of the query. Example:
IDVault.get("assetProp",dn,"user","LastName");
IDVault.execService(service)
IDVault.execService(service, param)
IDVault.execService(service, param, locale)
Executes an AJAX service and the result is used to refresh the content of the field. The service must be registered in the UI control registry. The first column of the result list result is used for the display value, the second one for the data value. Example :
var r=IDVault.execService("dnlookup2",params);
var res=r?r["_data"]["raw"][dn]["value"]:"error encountered";
field.setValues("IDVault.execService(\"dnlookup2\") :"+res);
This section lists functions used with the nrfRequest object in Roles Based provisioning request definitions. It includes:
Table 9-6 Role Request Properties
Returns True if this is an add operaton. Occurs when the AddedDN is not null.
public boolean isAddOperation() throws ActivityException
Returns True if this is a remove operation. Occurs when the RemovedDN is not null.
public boolean isRemoveOperation() throws ActivityException
Retursn True if the target DN is a user DN.
public boolean isTargetDNaUserDN() throws ActivityException
Returns True if the target DN is a role DN
public boolean isTargetDNaRoleDN() throws ActivityException
Returns True if the target DN is a container DN
public boolean isTargetDNaContainerDN() throws ActivityException
Returns True if this is target DN is a group DN.
public boolean isTargetDNaGroupDN() throws ActivityException
Returns the CN.
public String getCn() throws ActivityException
Returns the category type localized string.
public String getCategoryLocaleString() throws ActivityException
Gets the completed work flow e-mail address. This is a convenience method for the NrfRequest ECMA script object.
public String getCompletedWFEmailAddress()
Returns the Correlation ID.
public String getCorrelationId() throws ActivityException
Returns the decision date.
public Date getDecisionDate() throws ActivityException
Returns the description.
public String getDescription() throws ActivityException
Returns the end date.
public Date getEndDate() throws ActivityException
Returns the entity key.
public String getEntityKey()
Returns the preferred locale.
public Locale getLocale()
Returns either the Add operation or the Remove operation.
public String getOperation() throws ActivityException
Returns the request date.
public Date getRequestDate() throws ActivityException
Returns the requester.
public String getRequester() throws ActivityException
Returns the status localized string.
public String getStatusLocaleString() throws ActivityException
Returns the start date.
public Date getStartDate() throws ActivityException
Returns the status int value.
public int getStatusValue() throws ActivityException
Returns the source DN.
public String getSourceDN() throws ActivityException
Returns the source DN display name. This is a Role DN.
public String getSourceDNDisplayName() throws ActivityException
Returns the target DN affected by this operation.
public String getTargetDN() throws ActivityException
Returns the Target DN display name. If it is:
If it is a user, it returns first name + last name.
If it is a group, it returns the description.
If it is a role, it returns the description.
If it is a container, it returns the target DN.
public String getTargetDNDisplayName()
Returns the category type int value.
public int getCategoryValue() throws ActivityException