| Section | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
|
...
Many times the condition name.value.length > 0 can be dropped altogether and the rule can be simplified. This rule executes whenever a user enters a value into either the control named firstname or lastname because the firstname and lastname controls are on the left-hand side (LHS) right side of the assignment operator.
...
The rule validator described in detail below will help you detect this potential rule bug by displaying a validation error such as the one shown below. This form has two controls named HorseName.
JavaScript Reserved Keywords
abstract | catch | debugger | else | final | goto | instanceof | new | public | switch | transient | void |
| boolean | char | default | enum | finally | if | int | null | return | synchronized | true | volatile |
| break | class | delete | export | float | implements | interface | package | short | this | try | while |
| byte | const | do | extends | for | import | long | private | static | throw | typeof | with |
| case | continue | double | false | function | in | native | protected | super | throws | var |
Accessing Control Properties
Rules refer to form controls using the control's Name. Let's say you have a control which you named FirstName. You can refer to properties of this control using the syntax <Control Name>.<Property>. The current version of , supports the following properties:
...
Accessing Control Properties
Rules refer to form controls using the control's Name. Let's say you have a control which you named FirstName. You can refer to properties of this control using the syntax <Control Name>.<Property>. The current version of , supports the following properties:
- visible : Set to false to hide a control and true to make the control visible.
- value : Read or write the value of a control. This is not applicable to sections, tabs and other controls where it does not make sense to set a value.
- enabled : Set to false to disable (grey out) a control so that a user can not change its value and true to enable it. This is not applicable to sections, tabs and other controls that do not make sense to disable/enable.
- expanded : Set to false to collapse a group control (sections controls only) and true to expand a group control.
- selected : Set to true to make a tab the selected tab (tab controls only).
- valid : The value of this property is true if the control contains a valid value otherwise false. Validity is based on the control’s type. For instance a numeric control will be invalid if the user enters a string value that cannot be converted to a number. This property can be read as well as written.
- required : Set to true to make a control required and display the red asterisk. (NOTE: only affects palette controls and not controls generated from XSD schema data source). This is also a property of section controls. Setting a section required to false automatically sets all inner controls to not required.
- options : This property enables dynamic setting select control options (radio, dropdown & checkbox controls only).
- label : This property sets the label seen on any control including sections.
- help : This property sets the help text.
- hint : This property sets the hint seen on hover.
- status : This property sets the error message display whenever the control's value is invalid.
- clicked : This property works with trigger controls. Its initial state is false. When a user clicks a trigger its state turns true.
- printable: Set to false to remove the control from both the printable view and PDF submission document.
- itemAdded : This property works with repeat controls. Its initial state is false. When a user clicks "+" to add a repeat item AND when a repeat item is added via a Document URI as the form loads its state turns true.
- itemRemoved : This property works with repeat controls. Its initial state is false. When a user clicks "-" to delete a repeat item its state turns true.
- itemIndex : This property works with repeat controls. When an itemAdded or itemRemoved event fires the value of itemIndex is set. For itemRemoved events itemIndex will return -1. For itemAdded events itemIndex will give you the index of the added item
...
- form.load : This property is true when the form is first loading. It is useful for setting default values via rules that you need to be set before the user starts interacting with the form. This also holds true for flows. This property is true when each step of a workflow is first loading.
- form.unload : This property is true when users click the form's submit button. It is useful for setting control values just prior to the execution of the form's Doc Actions and Form Actions. This also holds true for flows. This property is true when the user clicks the continue button for each workflow step.
- form.positionUpdated : This property is used for the Geo location feature. You can fire a rule using this special identifier every time the position is updated.
Examples of identifiers used in rules are:
...
- Browser independence. We found it impossible to get these to run reliably in so many versions of so many browsers, especially IE. A bug in your rule (e.g. an infinite loop) will crash the browser and in some cases will require a Windows reboot. On the server, these run in separate threads with lower priority and timeouts so it will not impact the form server.
- The ability for the rule to do server-side things like http:get () to a database connector, invoke a REST service etc. These often reside behind the firewall and are not accessible to the browser.
- The rules are not exposed to the browser at all so any sensitive information in the rule (e.g. a password) won’t leave the server. However, we do not recommend putting any sensitive information in a rule.
- Rules can use information like the currently authenticated subject user id, name, email etc. though technically it would be possible to make this available on the browser if required. However, providing this information in the browser is a potential security hole.
- Rules can also modify a control – in theory, this can cause large-scale changes to the form’s valid state. Think of an optional XML complex type that has a deeply nested data structure inside it with some required and some optional elements. If any element has a value, all the other required elements become required. It’s much easier and efficient to analyze the form on the server although, technically, this is also possible in the browser. It can be extremely slow for large forms, especially in IE or if someone is running on a slower machine.
These pros of excuting rules server-side mitigate the couple cons:
- It makes offline forms difficult to implement. We are working on offline accessible forms especially for tablets.
- Potential the browser. It can be extremely slow for large forms, especially in IE or if someone is running on a slower machine.
There is a potential for performance bottlenecks. However, this is rare since rules are not compute intensive typically. We think the benefits outweigh the drawbacks here.
Dates and Times
There are several special considerations when writing rules using date, time and date/time controls. You can also find many working samples in the Rules Examples chapter.
...
As rules are executed on the server and not on the browser client side. Thus timing is effected by the performance of your server machine and the server's current load.
Rule Timeout
By default a rule that takes longer to execute then 5 seconds will be timed out by the Form Server. Customers using the in-house download version can customize this timeout. This is often necessary when rules have to perform longer running operations such as sending email messages, database stored procedures, etc. To configure the timeout add the following line to your web application containers property file. For the -tomcat bundle this file is <frevvo-home>\tomcat\conf\Catalina\localhost\frevvo.xml and is specified as follows:
| Code Block |
|---|
<Parameter name="frevvo.rule.timeout" value="5000" override="false"/> |
To set the timeout to 15 seconds set value="15000"
Rule Execution Priority
This experimental features lets you control the order of execution in complex rules usage. There is no UI for this feature. Please contact customer support for information.
An example usage: Rule1 is called when multiple form field values change. Rule2 has many XXX.value = ... that would trigger Rule1. If the rules engine happens to always picks Rule2 to execute first, you would execute Rule1 more than is needed. While rule ordering doesn't cause a behavior issue, if Rule1 happens to perform a more time consuming operation such as retrieving data from a database, this may cause a performance issue. Rule execution priority enables you to tell the rules engine to execute Rule1 before Rule2. Then each subsequent call to Rule1 would be prevented.the performance of your server machine and the server's current load.
Rule Timeout
By default a rule that takes longer to execute then 5 seconds will be timed out by the Form Server. Customers using the in-house download version can customize this timeout. This is often necessary when rules have to perform longer running operations such as sending email messages, database stored procedures, etc. To configure the timeout add the following line to your web application containers property file. For the -tomcat bundle this file is <frevvo-home>\tomcat\conf\Catalina\localhost\frevvo.xml and is specified as follows:
| Code Block |
|---|
<Parameter name="frevvo.rule.timeout" value="5000" override="false"/> |
To set the timeout to 15 seconds set value="15000"
Rules and Repeating Controls
...
makes certain data available to your rules. This includes information about the person currently using your form, the tenant and form information. You retrieve this data in your rule using the _data.getParameter('<data name>') syntax. Here is the list of available data:
...
:
- subject.id - logged in user's username.
- subject.first.name - Logged in users's First Name
- subject.last.name - Logged in users's Last Name
- subject.email - Logged in users's email address
- subject.roles - A list of all the roles for the logged in user (available in v4.1.5)user
- subject.reports.to - Logged in users's Reports To
- user.id - Owner of form/flow and user folder name in the filesystem
- user.name - TBD
The following additional data is available in v4.1.4 and later releases.also available:
- app.id - The unique id associated with a given application. See Sharing Forms
- app.name - The name of the application
- form.type.id - The unique id associated with a given form. See Sharing Forms
- flow.type.id - The unique id associated with a given flow. See Sharing Forms
- form.id - The unique form instance id. This id is unique for each for submission.
- form.name - The name of the form
- flow.id - The unique flow instance id. This id is unique for each flow submission.
- flow.activity.id - The Id of the current workflow activity
- flow.activity.name - The name of the current workflow activity
- form.extid - Client defined extId passed in the formtype Url parameter.
- flow.extid - Client defined extId passed in the flowtype Url parameter
- form.theme - Theme assigned to a form/flow.
- tn.id - the Tenant ID where a form/flow is located
- tn.name - the Tenant Name where a form/flow is located
Position Data
The following data is available when you enable your form's GEO Location feature:
...
| 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. In v5.0, the parameter syntax is: & Use ?_formTz= time zone string . In version 5.1 the parameter syntax is ?if the you are adding the timezone parameter directly after the form/flow URL and &_formTz= time zone string . Timezone strings can be found hereif you are adding the parameter after an existing URL parameter. . For example, to specify the Eastern time in version 5.1, the syntax would be zone as the first parameter after the URL use ?_formTz=America/New_York. Timezone strings can be found here. |
Users, Roles and Tenants Methods
...
The Quick Help button provides information about rules and documentation links to other topics.
Controls published with rules are visible here but not editable.
Prefix Property
Child/descendant controls of custom read-only controls are named with a prefix value. The prefix of these contained controls is editable and will be defaulted properly whenever the custom control is dragged more than once onto the form. In this way, you can write a separate rule to manipulate these controls within the 2nd and greater instances of the custom control. Refer to this documentation for the details.