getQuestionValue( )

Return a single question value for provided item path. The item path should be a whole path and should contain values for visitId, formId, and itemId. This function fetches values from questions on both repeating and flat forms.

All Visits cannot be used in the variable definition. If you'd like to fetch multiple values from a repeating form instance in a single function call, use thegetRFValues( ) function.

Note:

  • This rule does not support Visit Start Date items.
  • This is aggregation function, the rule is run for each form instance in the case where the target is on a repeating form.

Syntax

getQuestionValue('ruleVariable', eventInstanceNumber, formInstanceNumber, repeatFormNumber)

Parameters

Note:

If optional parameters are missing, the event instance number and form instance number are taken from rule target context.
Parameter Required/Optional Description
ruleVariable Required Variable to be retrieved. Must be a rule variable (added globally in the rule editor).
eventInstanceNumber Optional

Event instance number/cycle instance number.

To reference non-repeating visits, pass an empty string.
formInstanceNumber Optional

Form instance number.

To reference a non-repeating form, pass an empty string.
repeatFormNumber Optional

Repeat form number to reference items on a two section form.

Return value

The question value in the corresponding data type, or null if there is no value.

Note:

The value is returned even for deleted instances.
Question type Returned data type details.
Date Returned variable value will be a C1Date object in case of a variable being a partial date, or it will be a Date object in the case of the variable being a full date.

For additional information see Handle partial dates in custom rules.

Note:

When using date items, a null check must be included. See the example for more information.
Choice control:
  • Checkbox
  • Radio button
  • Dropdown
The returned variable value is a string in JSON format: 
"[{\"value\":\"3\",\"label\":\"TestLabel\"}]"
This can be parsed using JSON.parse or the helper function parseChoice.
  • parseChoice(result))
  • JSON.parse(result))

Examples

Example 3-97 Using getQuestionValue in 2-section forms

To use getQuestionValue for items inside table rows of 2-section forms, the syntax is:

getQuestionValue('ruleVariable', eventInstanceNumber, repeatNumber, formInstanceNumber)
// Get a value from an item in a flat form
return (getQuestionValue('text1');
 
 
// Get a value from an item in repeating form instance #1
// Pass an empty string to eventInstance
return (getQuestionValue('text1', '', 1);
 
 
// Get a value from a flat form in unscheduled visit instance #1
// Pass an empty string to eventInstance
return (getQuestionValue('text1', 1, '');
 
 
// Get a date value from a flat form
var res = getQuestionValue('dt1');
if(res !== null) {
  return res.getFullYear();
} else {
  // do nothing
  return;
}
 
 
//In a 2-section form, get a value from Form 2, Table Row 3:
return getQuestionValue('v2', '', 3, 2);

Parent topic: Multiple visit schedules and cycle visit functions