Entity form, its lifecycle, events and best practices for form rules (with practical examples)

Entity form & Edit form editor

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. Each form should be easily understandable, which can be achieved by organized placement of the required components on the form.

The name Entity form is derived from the fact that the form for each entity in the database is unique – it is linked to the particular entity, contains multiple fields, styles and can be connected to different entities. To set up a form according to your requirements, use the Edit form editor. It can be easily found on each entity available in App Configurator.
To find out more about setting up and styling entity forms, please check the App Configurator manual with examples.

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.
An important step that prevents you from implementing incorrect logic in entity form rules and from getting error messages while working with the form, is to understand how the entity form actually works and what is the logic behind its lifecycle and events.
Imagine a form lifecycle as actual responses of the entity form to form events. 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. OnLoad 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.

Good to know: 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.
Additionally, you must always take into consideration one more event:

• Async: Occurs when an asynchronous operation is called. This event operates independently of other processes and returns its result subsequently.

Form rules – Take control of form events

Have you ever wondered if any form components (fields/tabs) can be dynamically hidden or if it is possible to automatically assign certain values to fields when saving the form?
Most of basic form actions, as well as more complicated fetches on forms, can be achieved by using form rules. Form rules represent a sequence of steps executed on form-related events Load, Change and Save. They can be found in the Edit Form section of an entity in App Configurator and are bound to the form and its main entity.
For complete information on form rules, check the Form Rules Guide.

Best practices for form rules to keep in mind

1. Use OnLoad rule only for initialization handling actions.

OnLoad rules are the best option when it comes to handling initializations. They are designed and should be used for various steps handling actions connected to initialization of components or form styles. The reason for this is simple – users must wait for OnLoad 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 OnLoad rule, its execution time is minimal (unless you are handling great amount of conditions and steps in the rule).
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 OnChange rule.

2. Using the “otherwise if” part of the rule

Always use “otherwise if” part of the rule, even when it seems unnecessary.
One of the most common mistakes when setting up form rules is skipping the “otherwise if” part of the rule. There are situations when it seems logical that the rule should work in a certain way, even without the “otherwise if” part. Unfortunately, this assumption often leads to form rule errors or incorrect form behavior.
Good to know: 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 of a common mistake:
Imagine you want to change the color of the form field (City) to grey, when it is filled. 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 – each time the user opens the form, the rule checks if the field is filled and when it is, its color changes to grey. Simple, right?

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.

But then you want to add a new record and open a new form. What happens? The City field is grey even though it doesn’t contain any data. Why?

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.
In the rule above, only the step to color the field grey was set. After the rule was triggered, because the condition was met, the city field color changed to grey. However, the application itself doesn’t know that the field should be white again when re-opening the form and it does not contain any data. The rule itself isn’t reset every time a form is closed. That is why you must tell the app to change the City field color back to white, if it does not contain data (in this example by assigning normal style to it), as seen in the screenshot below:

3. Execution of an OnChange rule can be handled by IsLoaded and ChangedItem properties

One of the most common questions from the users when setting up OnChange rules is why they experience OnChange rule being triggered when loading the form, or why is the OnChange rule triggered repeatedly. Most of time the reason has to do with incorrect usage of the IsLoaded and ChangeItem property.
As mentioned earlier in this article, OnChange rule is always triggered at least once if OnLoad rule changes the value in any field on the form.  This has logical background – if you set up the step in OnLoad rule which changes a value of one of the fields, this change is done at the moment when the form is displayed on the screen. Therefore, a Change event is recognized by the application and OnChange rule is triggered (if the change meets the conditions set for the OnChange rule).
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.
ChangedItem property checks whether the change on the form occurs on the specified field.
Example of ChangedItem and IsLoaded use:
We want to show a text warning to the user after he/she deletes data from the City field and leaves it empty. Commonly, an OnChange rule is used for this case:

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.

How to set up the rule correctly?
You need to add two more conditions into the existing rule: one for checking which field was changed on the form, second one for checking if the form is already loaded, because you do not want to show the message when just opening the form. The correct rule would be:

We are using:
IsLoaded Equals True – because we don’t want to check this condition when opening the form; we want to check the condition when user makes a change on the City field
ChangedItem Equals address_city – because we want the rule to be triggered only if the City field was changed and not any other field on the form
Entity.address_city Does Not Contain Data – because we want to check whether the city field contains data after the user changed the value of the field.
“I experience OnChange rule being triggered even when having IsLoaded property true and ChangedItem set to correct field!”
This situation can occur in one specific case. If you are changing the value in the field in OnLoad rule and its change is being checked by OnChange rule.
Example IsLoaded (for this case):
We have an OnLoad rule which assigns a value to the city field when the form is loaded.

Then, we also have the OnChange rule, which shows users a warning text that the value in the City field was changed. We, of course, specify IsLoaded and ChangedItem properties.


Every step in the OnLoad rule which assigns a value to the field on entity form is considered a field change and triggers a corresponding OnChange rule.
By assigning a value to the form field by OnLoad rule we are changing the field. That results in a Change event which triggers the OnChange rule.
Important facts about IsLoaded property:

• For each entity field with an OnChange rule:
  If you set OnChange rule with IsLoaded equals false, the changes made to the entity will not trigger OnChange rule. The OnChange rule will only be executed during OnLoad event, if the condition is met.
• OnLoad rule steps that change values of entity fields will trigger OnChange rules when IsLoaded property equals True.

4. Do not load (fetch) entity in Can Execute rule (command rule), use OnChange rule instead.

Entity fetch is an asynchronous operation. That means that we don’t know exactly when it will return the result – the fetch.
While an asynchronous operation triggered by an OnChange rule runs, the user sees a loading screen in the application, since the rule waits for the result of the operation. However, when calling an asynchronous operation (fetch) in the Can Execute rule, the rule itself could be executed before it gets the asynchronous operation result and could cause incorrect behavior of the command in the application.
If you need to check a linked entity field’s value, visibility, etc. to make a command visible on form, we highly recommend using the following method to achieve it:

1. Create the needed fetch in OnChange rule and save its results in a shared variable
2. Use the shared variable in a Can Execute (command )rule condition to achieve the required behavior of the command

More tips and tricks?

If you want to explore more technical details of Resco Mobile CRM and other Resco products, make sure to join us at resco.next 2018 in Prague – our premier educational event focusing on all things Resco and business mobility. With a promo code PRGPR2018 you can book your conference pass until October 15 with a special 15% discount.