FindRFInstance( )

Find a repeating form instance that contains a value which matches the search value using a supplied operator.

This function is similar to FindMatchingRepeatingForm( ). However, it allows the rule designer to specify matching operands (=, >, <, >=, <=).
  • This function does not support choice questions such as drop-down, radio button, or check box.
  • Values in the custom function should be JavaScript variables or direct values. Do not use operand variables directly in the custom function expression.
  • If other operands/variables are to be used for a value, it has to be assigned first to the JavaScript variable and then used in the function expression.

This is an aggregation function. The rule is run for each form instance in the case where the target is on a repeating form.

Syntax

FindRFInstance (DateMask, 'variable1', 'compareOperator1', value1, 'variable2', ...)

Parameters

Note:

It is allowed to reuse variables passed into this function elsewhere in the rule expression, however you must add the variable as a parameter using single quotes.
Parameter Required/Optional Description
DateMask Optional Flag to specify how partial dates should be handled:
  • If null, ignores partial dates when doing comparisons.
  • If a value is provided (in string format), replaces the UNK component in the partial date with the specified value.

    For example: entering '10-Apr' substitutes with '10' every UNK value of Day (DD) component and with 'Apr' every UNK value of Month (MMM) component.

Note: Use mask only for date elements and do not use it for time elements. Any missing value in the time part is considered as 00.
variable(s) Required Item variable to search, passed in using single quotes.
compareOperator Required
Operator to use for the comparison of the provided variable and value:
  • =
  • >
  • <
  • >=
  • <=
value Required Value to compare variable with as a string.
  • Date values can be provided as a Javascript Date variable or as a string in the following formats:
    • 'Date(dd-mmm-yyyy)'
    • 'Date(dd-mmm-yyyy hh:mm:ss)'
    • 'dd-mmm-yyyy'
    • 'dd-mmm-yyyy hh:mm:ss'
  • Time values can be provided as 'Time(hh:mm:ss)'

Return value

Number (>0) that represents the index of the form instance where the matching value was found.
  • If multiple instances are found, only the first index is returned.
  • Returns -1 if no matches are found.

Usage tips

  • Use 'DD-MON' format as DateMask to substitute unknown (UNK) values in the partial date values. For example, if the mask is '01-MAR':
    Partial date value Masked date Notes
    'UNK-FEB-2020' '01-FEB-2020' Made effective for calculation using the day part of the mask.
    'UNK-UNK-2020' '01-MAR-2020' Made effective for calculation using both, the day and month parts of the mask.

Examples

Example 3-51 Raise a query if there is an instance of pulse greater than a given value

// Raise a query if there is an instance of pulse > 100
return (FindRFInstance(null, 'pulseVal','>', 100) > 0)?false:true;        //query is raised when false is returned

Example 3-52 Raise query if Date variable is on or after a given date value

// Raise a query if there's an instance where onDate is >= 10-Jun-2010
//(onDate is partial UNK-UNK-YYYY) 
return (FindRFInstance('10-Jun', 'onDate', '>=', '10-Jun-2010') > 0)?false:true;

Example 3-53 Raise query if Datetime variable is on or after a given datetime value

// Raise a query if there's an instance where onDateTime is >= 10-Jun-2010 11:12:15
//(onDateTime is partial DD-MMM-YYYY UNK:UNK:UNK)
return (FindRFInstance('10-Jun', 'onDateTime' , '>=', '10-Jun-2010 11:12:15') > 0)?false:true; 

//or
return (FindRFInstance('10-Jun', 'onDateTime' , '>=', 'Date(10-Jun-2010 11:12:15)') > 0)?false:true;

Example 3-54 Raise query if Time variable is on or after a given time value

// Raise a query if there's an instance where onTime is >= 11:12:15 
//(onTime is partial HH:UNK:UNK)
return (FindRFInstance(null, 'onTime' ,'>=', 'Time(11:12:15)') > 0)?false:true;

Parent topic: Repeating form functions