Form rules

Rules and examples
On Load On Change On Save On Create Select Form Row Script On Execute On Can Execute Cell Click Button Click On Item Added On Item Completed On Repeat On Delete Form rules Rules on the bulk update form Command rules Questionnaire Designer examples Rules editor Global constants

Warning

Work in progress! We are in the process of updating the information on this page. Subject to change.

Form is a screen in the application that contains numerous fields which either hold or await the data. It is a tool that enables system administrators to represent the database data and collect user data in a user-friendly way. Default behavior of an entity form can be changed using form rules, which control form events and provide actions that can take place if one of the events occurs.

Lifecycle of Entity Form & Entity Form events

Default behavior of an entity form can be changed using form rules, which control form events and provide actions that can take place if one of the events occurs. Form event is an action of a user or code, which invokes response action from the entity form. The main three events are:

Load: Occurs before the form is displayed on the screen. It occurs immediately after the user chooses to open an entity record from the List view screen. On Load rule connected to a Load event is activated on Load itself.
Change: Occurs after the form has been displayed on the screen and any change on it is recognized. OnChange rule connected to a Change event is activated on Change and Load events as well.
Save: Occurs after the form has been displayed on the screen, user hits the save button and the form is trying to get closed (off the screen). OnSave rule connected to a Save event is activated on Save itself.

Note	After the form is displayed on the screen, a Change event occurs as loading data into each field on entity form is considered a change of those fields. Therefore, On Change rules are triggered.

Use On Load rule only for initialization handling actions

OnLoad rules are the best option when it comes to handling initializations. Users must wait for On Load rule to be fully executed before they are able to see the form in a desired format. By setting up only the initialization actions in On Load rule, its execution time is minimal.

Set up in OnLoad rule:

Hide/Show fields
Enable/Disable fields
Hide/Show tabs
Assign styles to fields or to the entire form
Automatically assign values to fields, e.g. date & time, location, company number etc.

Do not set up in OnLoad rule:

Hide/Show/Enable/Disable fields and tabs dynamically. The actions related to changes on a form while working with it are better to set up in the On Change rule.

Using the “otherwise if” part of the rule

One of the most common mistakes when setting up form rules is skipping the “otherwise if” part of the rule.

Keep in mind that the form is reused while the application is running. What does this mean? If you set a style of a field by rule, without defining the “otherwise if” part, the style of the field on the form is saved. Afterwards, when you open a new form of the same entity, it simply uses the style you saved on the last one. Without using the “otherwise if” part of the rule to change the style back, the form is simply reused.

Example:Change the color of the form field (city)

For the Load event create an OnLoad rule which checks if the field contains data. If it does, you assign “greyFieldStyle” to that field. You don’t specify any “otherwise if” part, because the rule seems straightforward.

You open the form for the first time and its background is white, because the city is not filled. So we add a value to the City field and save the form. When re-opening the form, the city field is grey because it already contains data.

Then, you add a new record and open a new form. What happens? The City field is grey even though it doesn’t contain any data.

That’s because there is no “otherwise if” part of the rule specified, which would change the style back to white color if the field is empty. The rule itself is not reset every time a form is closed. That is why you have to set On Load to change the City field color back to white, if it does not contain data (in this case set the style back to Normal).

On Change rule should be handled by IsLoaded and ChangedItem properties

One of the most common questions from the users is, why they experience On Change rule being triggered when loading the form, or why is the On Change rule triggered repeatedly. In most cases, this is because IsLoaded and ChangeItem properties are not included or applied incorrectly.

To control the execution of OnChange rules we highly recommend using IsLoaded and ChangedItem property.

IsLoaded property checks whether the form is fully loaded and visible on screen with all the values assigned.

Note	During the load event each field on the form is populated with data. This change, despite the fact that it took place during loading, triggers the On Change rule.

ChangedItem property checks whether the change on the form occurs on the specified field.

Note	If not specified which field is to be changed, any change on the form will execute the On Change rule.

Example: ChangedItem and IsLoaded use case

We want to show a text warning to the user after he/she deletes data from the City field and leaves it empty.

At first sight, the rule above seems correct, however it will result in incorrect behavior for a Change event on the entity form. When the form loads and data is assigned to the fields, it is considered a Change event and the OnChange rule is triggered.

Two situations occur with this rule set:

When opening a new form: Since we didn’t use the ChangedItem property to specify which field change should the app check before showing the warning text, the warning is shown for every single field loaded on the form. So if you have 20 fields on the form and use the rule above, you will see the “City is empty!” message pop up 20 times – incorrect behavior.

When opening an existing form with the City field filled in: The message doesn’t show up after load and after deleting the data from the City field, the message shows up as expected. However, when modifying other fields on the form, the message also shows up. This is happening, because we did not specify which field the rule should check for changes before showing the error message. Every time the application recognizes a change on the form and the City field is empty, the message will be shown – incorrect behavior.