1

On Change

From Resco's Wiki
Jump to navigation Jump to search
Rules and examples

On Change rule icon 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:

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.

On Change: Postal code validation example

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: Placeholders and appearing fields example part 1(On Load)

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.

On Change: Placeholders and appearing fields example part 2

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.

On Change: Fill in the address of Invoice from the customer example

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.

On Change: Load reference from another entity example part 1

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.

On Change: Load reference from another entity example part 2

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.

On Change: Load reference from another entity example part 3

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.

On Change: Load reference from another entity: Order_priceperunit field to load reference from the Product_currentcost

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.

On Change: Count the number of associated contacts example

Used fetch:

On Change: Count the number of associated contacts (fetch) example

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.

On Change: Summation of Opportunities estimated revenue (for account) example

Used fetch:

On Change: Summation of Opportunities estimated revenue (for account) (fetch) example

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.

On Change: Simple calculating operation example

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

On Change: Volume discount classified by product example

Optionally, you can calculate volume discount in percentage via variables:

On Change: Volume discount classified by product in percentage example

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).

On Change: Reload the unassociated entity list example part 1

Add the unassociated Contact list to the Order form and add the following filter.

On Change: Reload the unassociated entity list filter example part 2

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.

On Change: Reload the unassociated entity list part 3

To display the Contact list while creating a new record, add the following On Load rule.

On Change: Reload the unassociated entity list part 4

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.

On Change: Clear the address fields if the city is changed part 1 (cell on view is set to kind=edit)

The postal code and street field are cleared if the city field is changed.

On Change: Clear the address fields if the city is changed part 2 (rule)

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
  • 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

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.

On Change: Additional question is displayed in questionnaire example

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.

On Change: Automated date of next inspection example

Example: Populate the questions with data from shared variable

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.

On Change: Populate the questions with data from shared variable example

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.

On Change: Appends text to the subject of the activity when you reschedule the activity example



Was this information helpful? How can we improve?