| Section | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
|
...
- form.load : This event is occurs when a form or workflow step loads for the first time. It is useful for setting default values via rules that you need to be set before the user starts interacting with the form.
- form.unload : This event is true when users click the form's Submit or a workflow's Continue button. It is useful for setting control values just prior to the execution of the form's Doc Actions and Form Actions. If you have a rule in your form that changes any control(s) after clicking Submit, thereby making the form invalid, the form will no longer be submitted and the invalid form will redisplay. Form and Document actions will not execute, PDFs are not generated, invalid controls become highlighted as expected and form.unload output displays in the debug console.
- form.positionUpdated : This event is used for the Geo location feature. You can fire a rule using this special identifier every time the position is updated.
- form.activate: This event indicates that a workflow has navigated to a step. If form.activate is true, the workflow just moved to a step. Use the _data.getParameter to determine what step that is.
- form.deactivate: This event indicates that a workflow has left a step. If form.deactivate is true, the workflow just left a step. Use the _data.getParameter to determine what step that is.
form.load vs form.activate
...
Every control has a Properties icon. Click the "+" to expand the Properties. You will see a list of all the properties that are applicable to this control. Note that even the "form" itself has a Properties icon which show that the form has form.load and form.unload properties. LoanNumber is a quantity control and thus has all the properties you expect for this control type such as LoanNumber.required, value, visible, etc.
Refer to Rule Editor Functions for an alternative method of composing rules within the rules editor.
...
When you are designing a form/workflow with many objects and a lot of business rules, reduce the number of page reloads when switching between the designer view, rules view, and the test view by clicking the save and test icon. Save and Test checks for Rule errors before the test popup displays. If rule validation errors are detected, the designer is notified and given the option to correct before the Test popup is displayed.
...
The validator also supports global directives. Use the global directive to identify additional global objects and functions defined in the execution environment and made available to the rule for which it is not appropriate to include a var statement in the rule code itself. One directive can be used to list all additional globals on a single line. Currently there are no known cases requiring the use of the global directive.
Rule Editor Functions
The Rule Validator includes an enhanced editor designed to provide an easy experience when developing rules. The rule editor box includes the following features:
| Features | Description |
|---|---|
| Line Numbers | Line numbers in the rule code editor make it easier to correlate reported validation errors with the line of code. |
| Bracket auto close | Type a {, ( or [ and the closing bracket is automatically inserted. |
| Match Bracket | Place the cursor on a bracket and both it and the matching bracket are shown in a matching distinctive color (green). |
| Syntax Hi-lighting | JavaScript syntax hi-lighting with keywords, variables, comments, etc. shown in distinctive colors. |
| Auto Indent | New lines are auto-indented according to generally accepted code formatting rules. |
| Code Folding | Bracketed code blocks (functions, if-then-else blocks, etc.) are collapsible. Click the |
| Full screen edit mode | Expand the editor to full screen mode if you need more space to work. Click the |
| Auto Complete/Hinting | When composing a rule, the designer can pick from a list of available controls and their properties directly within the rule editor. The pick list is context sensitive and will behave differently based on where the cursor is located when it is invoked. When on a blank space or immediately following an open bracket/brace, it can be manually invoked using Ctrl-Space to bring up a list of controls. Typing a dot (.) immediately after a control name or after the index ("[i]") that follows a control name will automatically bring up a context sensitive pick list of properties applicable to that control for selection. You can type the first letter of the item you are looking for and the property starting with that character will be highlighted in the list. Continue typing and the matching options will progressively narrow to the characters typed. Double click your choice using the mouse or press the Enter key to select an item. Any other key dismisses the pick list. . See the example below. |
| Help | The help icon displays a small help window listing the hot keys described above - (F2, ESC and Ctrl-Space) |
...
The easiest way to minimize mistakes in control names when writing rules is to use the Auto Complete/Hinting feature in the rule editor. Let's say you want to compose a rule that will populate the FirstName field in your form with the first name of the logged in user when the form loads. This rule using the Built-in Data in conjunction with the form.load rule identifier will accomplish this.
...
Add the remainder of the rule. The closing bracket will already be there. Of course, you can still use the Form Outline to help you when composing rules.
...
This example shows a CUSTOM event. These events are created by adding frevvo.log() calls to your rules. Custom log messages are useful when you need even more debugging output. See Custom Logging for more details.
| Note |
|---|
Doc URI write methods information, which occur when the form is submitted, do not appear in the debug console output. |
...
Rule execution can be profiled to determine how much time each rule takes to execute. This can help you tune and improve performance in forms that use a lot of business rules. To turn on profiling in the log files set the rule-debug=INFO or higher. See rule debugging for setting log levels. Profiling output is also displayed in the Debug Console.
...
| Info |
|---|
This example shows the syntax to use if you to turn off encoding for an http.post that already has up to 4 arguments: http.post(url,null,null,null,false). The encoding argument always goes in the last position no matter how many parameters the method has. |
Error Handling in Rules
When using an http(get) method in rules, it's a good idea to also handle error states within the rule. If there is an error with the http(get) or there is no match for your query, it can cause the form to stop working without much explanation. To prevent that situation, include an if/else statement that returns an error message in the case of null results, and otherwise runs the rule normally. Here is an example of a rule that reads from a google sheet to get a Full Address. The rule first checks for errors, and uses the variable fi to pass either an error message or the correct results to the Full Address control. If the results are null (meaning there was an error), the Full Address control will show "Error." If there are results but no match for the query (state either MA or CT), the Full Address control will show "No Match." If neither of those states are true, the Full Address from the results will populate in the control as desired.
| Code Block |
|---|
/*member fulladdress, results, password, user*/
if (form.load) {
var x;
var opts= [];
var headers =
{"user":"<your Google id>","password":"<your access token>"};
var readquery = '/google/spreadsheets/query/key/<your spreadsheet key>?wsname=<your worksheet name>&query=state=MA or state=CT';
eval('x=' + http.get(readquery,headers));
//Error Handling in the Rule
var fi = '';
if (x.results == null) {
fi = 'Error';
} else if (x.results.length === 0) {
fi = 'No Match';
} else {
for (var i=0; i < x.results.length; i++) {
fi = fi + '\n' + x.results[i].fulladdress;
}
}
FullAddress.value = fi;
} |
Dynamic Content
Real business forms often require dynamic content in dropdown list. Often based on the value entered into one form field, the values in other fields or options available in select controls need to be dynamic.
...
Reusing Data from a Web Service
The example above uses the database connector, which returns a clean json that doesn't cause any problems when it is copied into a text field. The json returned from other services might included extra spaces or other characters and might require trimming. This can cause an error such as 'SyntaxError: Unexpected token in object literal'.
You may need to add this code, which removes spaces from the json string, to your first rule:
| Code Block |
|---|
var json = http.get(requestUrl); jsonUserData.value = json.replace(/[\n\t\r]/g,""); |
...
- FirstName.value - only for parameters bound to a control in your form.
- {FirstName} - only for parameter used in http get templatized URI.
- _data.getParameter('FirstName') - if used anywhere else in a rule other than a URI.
...
LDAP supports both the standard subject attributes and custom attributes. When a user is successfully authenticated by the LDAP security manager, Live Forms automatically retrieves Last Name, First Name and Email Address for this user from the LDAP server. You can retrieve custom attributes in addition to the standard ones from Active Directory and pull the data into your form/workflow using business rules.
Rules can use built-in methods to populate controls on a form/workflow with the information for the logged in user. The rules use the _data.getParameter syntax, For example, the business rule shown fills the respective form fields with the First/Last Names and Email Address of the logged in user.
...
Attributes with more than one value are also supported. For example, The carLicense attribute can return multiple licenses. You can write a rule to populate dropdown options with those values. Make sure the carLicense attribute is added to the custom field on the LDAP Configuration screen and of course, there are multiple carLicense attributes, each one containing a different value for the dropdown options, set up for appropriate users on the LDAP server.
...
If these methods are used in rules a the designer will see a message in the Debug Console urging that the methods listed above be used instead.
| Note |
|---|
When you test a form in , the formTz parameter is automatically appended in the URL. Your form will load with the values specified in your rule. However, when you copy the share URL, you MUST append the formTz paramater. currentTime(), currentDate() and currentDateTime() will not work in a form.load rule unless you specify a timezone on the form's URL via the _formTz URL parameter. This is because the form server needs to know the timezone in which to return the date and time. If you do not specify a _formTz the methods will return null and the control values will remain blank. Use ?_formTz= time zone string if the you are adding the timezone parameter directly after the form/workflow URL and &_formTz= time zone string if you are adding the parameter after an existing URL parameter. For example, to specify the Eastern time zone as the first parameter after the URL use ?_formTz=America/New_York. Timezone strings can be found here. Refer to this documentation for more information. |
...
Here is a snippet of debug console output. The frevvo.log() message Event type displays as "CUSTOM". In this example the rule called the method frevvo.log('ERROR', 'Loading tenant roles...'); The message appears in red because all ERROR level log messages automatically are colored red.
See the debug console topic for full details of all the console output information.
...