On Change
| Rules and examples |
|---|
|
Rules are client-side scripts (no-code business logic) that are executed when a user of the mobile app interacts with the app. The On Change rules are checked when any field is modified. Rules are managed using the rules editor, usually in Woodford.
On Change rules are available for the following user interface components:
- Forms
- Editable views
- Questionnaires
- Schedule Board
IsLoaded
IsLoaded is a variable that checks whether the form or questionnaire is fully loaded and visible on the screen, with all the values assigned. Use it to differentiate between the initial loading of a form and manual user change.
| If | IsLoaded | Equals | True |
| Warning | Inclusion of isLoaded property is strongly recommended. Otherwise, it could negatively impact performance or even lead to a "Too many nested rule scripts" error. |
ChangedItem
The ChangedItem property checks whether the change on the form occurs on the specified field.
| If | ChangedItem | Equals | address1_city |
| Warning | Inclusion of ChangedItem property is strongly recommended. Otherwise, it could negatively impact performance or even lead to a "Too many nested rule scripts" error. |
Forms
Forms display the details of a particular record and allow editing of the record fields. The default behavior of an entity form can be changed using form rules. On change usually serves as a field modification based on input or simple field validation.
- Rule execution
- When you modify any field.
- When the form is loaded (a new form starts empty, then the values are changed as they are loaded from the database and displayed). This can be disabled by "IsLoaded" condition.
- When an associated/related record is created or modified. This option must be enabled in the properties of an associated list. Switch to the Properties tab and enable Controls > Trigger OnChange event (more info).
- Setting a value inside the On Change rule for a field placed on the form triggers the On Change rule again. This can be disabled by "ChangedItem" condition.
Lists on forms
Forms can include lists of related or unrelated records. For example, an account form can list its related contact persons. By default, changes on the lists do not automatically trigger on change rules for the form. However, this can be useful.
For example, your order form may include a list of order products. When you add another product to your order, you may want to recalculate your total order value, displayed on the form. To accomplish this, you must enable Trigger OnChange event in the list properties.
- Multiple lists
- You can add the same entity to a form multiple times. For example, the account form can include a list of active contacts and another list of inactive contacts. If at least one of the lists has Trigger OnChange event enabled (and both of the lists use the same relationship), a change in either list will trigger On Change.
- When writing the On Change rule, in the first condition ("If ChangedItem Equals ..."), depending on your Woodford version, you can see either multiple entries (one for each list) or only one entry for all lists that use the same relationship. The behavior in the app does not change: the rules engine does not differentiate between multiple lists with the same relationship.
Example: Postal code validation
When a user enters information into a field, you may want to verify that the format is correct. In the rule below, we verify that the postal code field matches the expected format.
Note the three conditions:
- IsLoaded Equals True – because we don’t want to check this condition when opening the form; we want to check the condition when the user makes a change on the field.
- ChangedItem Equals PostalCode – because we want the rule to be triggered only if the Postal Code field was changed and not any other field on the form.
- Entity.PostalCode Does Not Match Regex – because we want to check the format of the field after the user changed the value of the field.
Example: Placeholders and appearing fields
When we create a new record, a placeholder is assigned to the Main Phone field while the other two (email address, web site) are set to not visible. If the Main Phone is filled, the Email field is assigned a placeholder and set to visible (the Website field remains hidden). Then, if the Email is filled, it's assigned a placeholder and set to visible.
- On Load part
In the On Load part of the rule, we prepare the form for a new record by:
- filling the placeholder in telephone1 field, and
- hiding the emailaddress1 and websiteurl fields.
- On Change part
In the On Change part of the rule, we define how the form will act in case of change. If the telephone1 field is filled with data, we fill in the placeholder for emailaddress1 and set it to be visible.
| Note | Is Loaded equals true is important as we do not want the rule to be triggered by the placeholder for telephone1 which we set in the On Load. Entity isNew condition ensures that the rule is only executed in case of a new record. Entity E-mail and Web Site does not contain any data conditions prevent the repetition of the rule in case we already filled email or website and decided to change the telephone number. |
The rule continues similarly for email. If the emailaddress1 field is filled in with data, we fill in the placeholder for websiteurl and the field is set to be visible.
Example: Fill in the address of Invoice from the customer
In this example, the address of the Invoice is automatically filled from the Customer.
The following rule contains two conditions. Both conditions check whether changeditem equals the Customer field and if it contains data after the change. The difference is the first condition checks if the customer is a type of Account. If it is, we create a variable Account, load reference from the account, and fill the address fields into the Invoice. In the second condition, we check whether the customer is a type of Contact. If it is, we create variable Contact, load reference from contact, and fill the address fields into the Invoice.
| Note | We have to check the type of Customer. Otherwise, we do not know where to load the reference from. |
| Note | This rule is applicable to any entity containing a lookup field to another entity (Customer field in this case). |
Example: Load reference from another entity
This example is a showcase of loading references from one entity to another. Let's say, "we want to have a detail on the (Account) form containing primary contact information (Contact)." First, we must create a new detail and add a primarycontactid field.
We create a shared variable called primary_contact (as we store contact record inside, we have to choose the shared variable to be the contact entity type). Then we add a condition: if the form is loaded and the primary contact field is changed, we check if it contains data. We assign the Primary Contact record to the shared variable primary_contact if it does.
This shared variable now contains the primary contact with all its data, which means we can add different fields of this shared variable to the account form.
To see the rule execution in the app, click here.
Example: Load reference from another entity 2
In this example, we want the Order_priceperunit field to load reference from the Product_currentcost.
If Product of the Order changes, we create a variable var4, which loads reference from the selected Product. Now, we can assign var4_currentcost to the Order_priceperunit field.
Example: Count the number of associated contacts (for account)
We create shared variable "contactCount" (integer). If the parentcustomer for contact changes (see note), we create the variable "count" (integer), where we load all contacts related to the account through the Customer lookup field and count them. If the variable "count" contains data, it's assigned to the shared variable "contactCount". The shared variable can then be placed on desired form list.
Used fetch:
| Note | Trigger OnChange event option must be enabled for the list (Contact). |
Example: Summation of Opportunities estimated revenue (for account)
As in the previous example, we use loadaggregate operation with a slightly different use case. We want a summation of estimated revenue on Opportunities (in Euro currency) related to the actual Account.
If there is a change on the Opportunities list, variable Counter (integer) loads aggregate Opportunities on the list and sums the estimated revenue. If Counter contains data, we concat Counter value and Euro symbol and assign it to the shared variable Estimated_Revenue.
Used fetch:
| Note | Trigger OnChange event option must be enabled for the list (Opportunity). Additionally, you can add another branch to the rule to fetch Opportunities with different currencies and assign them to another shared variable. |
Example: Simple calculating operation
If the user changes quantity or priceperunit, then we create variable var1 where we divide priceperunit by 5 (as we set the tax to 20%) and variable var2 where we multiplicate var1 by quantity. The result (var2) is then assigned to the field Tax.
| Note | If you want to add a currency symbol to the currency field (in our example, the Tax field), you must format the field as Single line of text. In the On Change rule, then add a string variable step where you concat the calculated variable and the currency symbol. |
Example: Volume discount classified by product
In this example, we specify the volume discounts for different products at different volumes.
If the quantity or product is changed, the rule is triggered. We classify products and then the volume levels with discounts. For Handrail, we have 4 levels of volume, and each category has a specified volume discount:
| Volume | Discount | |
|---|---|---|
| 1 | <=100 | 0 |
| 2 | <=500 | 800 |
| 3 | <=1000 | 1500 |
| 4 | >1000 | 3000 |
Optionally, you can calculate volume discount in percentage via variables:
Example: Reload the unassociated entity list
In this example, we add an unassociated entity list on the Order entity. The unassociated entity list is the Contact entity. We want to display those contacts which belong to the order customer and are the contact type = Shipping. If the customer changes, the unassociated list is reloaded and updated with new contacts.
We have to define the Contact type field (add Shipping) in Admin Console (do not forget to enable the field in Woodford).
Add the unassociated Contact list to the Order form and add the following filter.
Now, add the On Change rule. If the customer is changed, the Contact list isloaded is set to false and then true. This causes reload, and the new contacts are loaded.
To display the Contact list while creating a new record, add the following On Load rule.
Views
On Change rules can be used with views, but only when the Editable field is set. (Editable field, list, or editable grid is a feature that allows users to edit one or more records directly from the view, without a need to go to the form of a record.)
- Rule execution
- When you modify an editable field.
Example: Clear the address fields if the city is changed
Set all the fields (also those meant to be affected by the change) as edit or directedit type.
The postal code and street field are cleared if the city field is changed.
Questionnaires
Editing rules allow you to further customize the questionnaire form’s design and usage (hide or disable form fields, assign values to them, etc.).
- Rule execution trigger
- When any value in the questionnaire is modified
- When the questionnaire is first displayed
- When a repeatable group is repeated
- When a repeatable group is deleted
- Rule execution order
- First, the main questionnaire change script is executed.
- Then, every group change script is executed.
Example: Additional questions
If the user answers a question in a certain way, you may want to display additional questions. For example, if the answer to the question “Are you married?” is “Yes”, an additional question “Partner's name” is set to be visible.
Example: Automated date of next inspection
If the user answers a question in a certain way, another question is filled in, based on the answer. For example, you can count the next inspection date based on the periodicity of inspections.
This example is an On Change addition to the On Load rule: Populate the questions with data from regarding lookup entity 2.
If the equipment question is changed, we assign this changed value to shared variable Asset. If the Asset variable contains all the data we want to use in questionnaire, it is assigned.
Schedule Board
In the Schedule Board, the On Change rule triggers when a task is rescheduled. The event is triggered when you:
- drag a task to a different time/resource
- modify the time or resource on the task properties
| Note | When you drag a task to a different resource and time, the rule is actually executed three times (every time with a different value in the ChangedItem variable): once for the start date, end date, and resource. |
Example: Appends text to the subject of the activity when you reschedule the activity
If the scheduled start for the activity is changed, appends (rescheduled) to the activity subject.
