FindMatchingRepeatingFormWithinRange( )

Find an instance of a repeating form, identified by the form ID, that matches the item value provided as a search key. The search can be based on search keys or date ranges.

  • You cannot use drop-downs, radio buttons, or checkbox values as function parameters or as a target.
  • The first two parameters should always be the date range. Additional search keys may be provided after that.
  • This function also considers entries where the dates are null.
    If any repeating form instance has a null start or end date then the system assumes a date in order to successfully perform the date range overlap check:
    • If the start date is null then the system assumes it to be 01-Jan-0001.
    • If the end date is null then it is assumed to be 01-Dec-3099.
  • If a variable is designed to hold a partial date then provide the value for that parameter in the same partial date format. You can use partial dates in the following formats:
    • <dd-mmm-yyyy hh:mm>
    • <dd-mmm-yyyy hh>
    • <dd-mmm-yyyy>
    • <mmm-yyyy>
    • <yyyy>

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

FindMatchingRepeatingFormWithinRange('startDateVariable',startDateValue, 'endDateVariable', endDateValue, 'variable1', value1, 'variable2', value2, ...)

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
startDateVariable Required Date item on a repeating form, used as the start date for the date range to evaluate.
startDateValue Required Date value for the start date of the date range. This must be provided in a string format, must be be hard-coded and cannot be rule variables:
  • Dates must be provided inside the string 'Date(dd-mmm-yyyy hh:mm:ss)'.
  • You can use partial dates in the following formats:
    • <dd-mmm-yyyy hh:mm>
    • <dd-mmm-yyyy hh>
    • <dd-mmm-yyyy>
    • <mmm-yyyy>
    • <yyyy>
  • Times must be provided inside the string 'Time(hh:mm:ss)'.
  • You can use partial times in the following formats:
    • <hh:mm>
    • <hh>
endDateVariable Required Date item on a repeating form, used as the end date for the date range to evaluate.
endDateValue Required Date value for the end date of the date range.

Consider same requirements as in startDateValue paraemter.

variable(s) Optional Item variable to search, passed in using single quotes.
value(s) Optional Search value(s) for the given variables. These must be hard-coded and cannot be rule variables.

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.

Note:

In dates, UNK values are considered to match any other value. For example: 'Date(01-Feb-2022)' and 'Date(20-Feb-2022)' are both considered as a match of an entry with UNK-Feb-2022 date value.

Examples

Example 3-50 Raise a query if any instances exist where a) onset date is between Jan 1 2020 and March 1 2020 and b) symptom = "headache"

// Given 5 repeating form instances with items "onsetStart", "onsetEnd" and "itmSymptom":
if (FindMatchingRepeatingFormWithinRange('onsetStart', 'Date(01-JAN-2020)', 'onsetEnd', 'Date(01-MAR-2020)', 'itmSymptom', "headache") > 0) {
  return false;
} else {
  return true;
}
 
// Fires query if any of the 5 instances contain onset dates between Jan 1 2020 - March 1 2020 AND itmSymptom = "headache"

Parent topic: Repeating form functions