| 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
Avoid using JavaScript Reserved Keywords as control identifier names as these words have a special function in the JavaScript language. Click here for a list.
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:
...
- 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:
...
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.
...
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.
Rules and Repeating Controls
...
Rules and Repeating Controls
If you have a repeating control in a form that itself contains a repeating control, you cannot apply a rule to the "inner" repeating control, since there's no way to tell which of the inner repeating items goes with which outer repeating item.
...
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:
...
- tn.name - Tenant Name
- 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.