About relation mapping definition for repeating forms

There is a way to define a relation between two repeating forms (child and parent) through the Relation Mapping Definition field. Implementing a relation definition reduces the amount of threads that run with rules using aggregate functions, which are used to get data from other form instances, and improves the system performance.

Note:

This field is only available when rule target is on a repeating form.

You must declare at least one variable (any question) from the parent repeating form and from the child repeating form to establish the possibility of a parent-child relationship. If the rule doesn't reference two repeating forms, and a relation mapping definition is set, an error is thrown when the rule is saved.

Consider the following to set the Relation Mapping Definition:
  • You must select a relation item (defined as a rule varible) that exists in the same repeating form as the rule target (child form).
  • The item selected as the Relation Mapping Definition must contain values that correspond to the instance numbers of the related parent table. The expected format is a whole number.

    This means that, given that in the child form each row is related to a given row from the parent table, in the child form you must have a field in which you enter the instance/row number from the parent form to which it is related to. This field in the child form, which contains the instance number from the parent form, must be used for the Relation Mapping Definition.

  • In the rule expression you still need to use an aggregate function to get data from parent table.

    For example: In a rule where date of change (form1) must be prior or the same as date of recovery (form2), use the event number in form1 to find the corresponding date of recovery in form2.

    Variables:
    var advnum        // event number - item in child table (rule traget form) which will be the relation item and contains the instance number of parent table
var intdat        // date of change in form 1 (child form)- item to be used in rule logic
var recdat        // date of recovery in form 2 - item from parent table to be used in rule logic, when updated it will trigger rule execution in child form
    Relation Mapping Definition:
    Parent Form Instance Number <=> advnum
    Expression:
    var aenum = advnum;
var rfdata = getRFValues(aenum, ["recdat"] );                              // aggregate function that retrieves 'recdat' variable from parent form where instance number equals the value entered in 'advnum'/'aenum'
var recdt = rfdata.exists && rfdata.recdat ? rfdata.recdat : null;         // null check and local variable value assignation

if(recdt !== null && partialDateDiff(recdt,true,intdat,true,'Day') < 0)    //evaluates if difference with given date is < 0 (if recdt happens before given date)
{   
    return false;                                                          //triggers query
}
else
{
    return true;        
}
As a result of the relation mapping definition:
  • If a user updates rule variable item on the parent form:
    • Rule execution logic loads data of the relation item and generates a list of instances in the child table that need to be evaluated and updated. These instances are those for which the relation item value is the same as the instance number of the from instance that was updated in the parent table.
    • Only the corresponding instances of the child form are evaluated and updated.
  • If a user updates rule variable item on a child form, the rule runs only on the current instance.
  • If a user updates rule variable item on any other form that impacts the rule, the rule runs for all target form instances as it happens without mapping definition.

Related Topics

Parent topic: Create rules using the rule editor