getValues( )

Use this helper function to fetch values for one or more variables across multiple visits, in an array format ordered by visits.

This is an aggregation function. The rule is run for each form instance in the case where the target is on a repeating form. For empty rows in repeating forms and two-section forms, only rows that were entered and then cleared will be included. Rows that never had data entered into it, won't be returned.

Syntax

getValues('var1', 'var2', ...)

Parameters

Parameter	Required/Optional	Description
`'var1', 'var2', ...`	At least one is required.	Rule variable names that define the visit, form, or item to be retrieved.

Return value

Returns true on success; otherwise, false.

Also, during the call to this function, passed in rule variables (var1, var2, …) are redefined with the gotten value. As a result, each variable holds an array with attributes.

WARNING:

Rule variables will be redefined to null if there is no data elements related to this variable. For this reason you should always validate if the variable contains any array elements before you use it for processing data.

Each item in the array, for example var1[0], contains the following information as attributes:

Attribute	Description
`var1[0].visitName`	The name of the visit.
`var1[0].deleted`	True if repeating form instance is deleted.
`var1[0].tableRowInstance`	The repeating table row instance in case it is within a table.
`var1[0].branchName`	Name of branch.
`var1[0].eventType`	Type of visit: Scheduled Visit Unscheduled Visit Event
`var1[0].formRepeatNumber`	The repeating form instance number in case form is a repeating form.
`var1[0].value`	Data element value, or `null` if values were cleared. Date elements: The returned variable value is a `Date` object in the case where the variable is the full date. The returned variable value is a `C1Date` object in the case where a variable is a partial date. For `C1Date` objects (partial dates), date values must be fetched using date parts such as `item.value.day`, `item.value.month`, and so forth instead of just `item.value`. `// Sample JSON response for a partial date item: [ { "visitName": "visit1", "deleted": false, "tableRowInstance": null, "branchName": null, "eventType": "ScheduleAbleVisit", "formRepeatNumber": null, "value": { "partialDate": true, "date": null, "day": "UNK", "month": 2, "year": 2021 }, "cycleNumber": null, "empty": false, "treatmentArm": null } ]` Choice control elements: If the variable is a choice control (checkbox, radio, or dropdown) then the returned variable value is a string in JSON format: `"[{\"value\":\"3\",\"label\":\"TestLabel\"}]"` This can be parsed using `JSON.parse` or `parseChoice( )`.
`var1[0].cycleNumber`	The cycle number of the visit in case it is in a cycle.
`var1[0].empty`	True if value was cleared or never entered in repeating form.
`var1[0].cleared`	True if repeating forms instance is cleared.
`var1[0].treatmentArm`	The treatment arm.

Usage tips

If you are working with variables defined for -Any Visit- you must use this helper function to get the values and use them in your expression. You can't work with this type of variables directly in your logic. Use the following format, where 'variable' is your Any Visit type variable:
```
getValues('variable')
```
This type of variable definition allows you to work with data collected in forms that are not present in the same visit as the target form in which you are creating your rule. For more information see Define rule variables.
The amount of data which is returned by getValues( ) can be significant, specially if there are multiple instances of the question; for example if the question exists in more than one visit or if it is part of a repeatig form. This can impact performance, so avoid using this function unless it is really necessary.
If you don't need to retrieve all values from one or more variables from all instances, try using other functions that return the data that you need. For example, if you need to check whether a variable exists in a form or not, it is prefered to use simpler helper functions, such as ListRFInstances() that would return relevant, but less data.
```
//Avoid
var form2dt1 = getValues(form2dt1);

//Recommended
var form2dt1=ListRFInstances(form2dt1);
```
Review examples in ListRFInstances( ).
Once you have passed a variable into getValues( ), it cannot be reused as a discrete value elsewhere in the rule. If you need to reference the discrete value for the row and visit elsewhere, you need to declare a second variable.

Examples

Example 3-103 View results of the getValues function call for a single item

// this can be helpful during rule development to view the results returned by the getValues function
// using a read-only text field as the target
 
var val = getValues("item1");
if (val == true) {
    return JSON.stringify(item1);
}
 
/* example results:
[
    {
        "visitName": "visit1",
        "deleted": false,
        "tableRowInstance": null,
        "branchName": null,
        "eventType": "ScheduleAbleVisit",
        "formRepeatNumber": null,
        "value": "Test",
        "cycleNumber": null,
        "empty": false,
        "treatmentArm": null
    },
    {
        "visitName": "visit2",
        "deleted": false,
        "tableRowInstance": null,
        "branchName": null,
        "eventType": "ScheduleAbleVisit",
        "formRepeatNumber": null,
        "value": "Test",
        "cycleNumber": null,
        "empty": false,
        "treatmentArm": null
    }
]
*/

Example 3-104 Sum all tumor diameter values across all visits

var sumTotalLongestDiameter = -1;
  
function calculateTumor(item, index)
{
    if ( longestDiameter[index] !== null )
    {
        sumTotalLongestDiameter += longestDiameter[index].value;
    }
}
  
var rc = getValues("tumorID", "longestDiameter");
  
if ( rc === true )
{
    tumorID.forEach(calculateTumor);  
      
    // Set the value for the current row where this rule runs
    return sumTotalLongestDiameter;
}

Example 3-105 Sum tumor diameter values across all visits, excluding the Screening visit by using a filter function

var rc = getValues("tumorID", "longestDiameter");
  
//filter by visit name
function filterFunction(item) {
  return item.visitName  !== 'Screening';
}
  
var sumTotalLongestDiameter = -1;
  
function calculateTumor(item, index)
{
    if ( longestDiameter[index] !== null )
    {
        sumTotalLongestDiameter += longestDiameter[index].value;
    }
}
  
if ( rc === true )
{
    //exclude Screening visit
    var filterResult = tumorID.filter(filterFunction);
    filterResult.forEach(calculateTumor);
      
    // Set the value for the current row where this rule runs
    return sumTotalLongestDiameter;
}

Example 3-106 Find the previous/next value with target and operands on the same form

Rule Variables:

brDateForFunc - rule variable which references date.
brDate - rule variable which references date (the same as the first one just with different name in case the same items on different visits should be compared).

var visitName = getCurrentVisitPropertyValue("visitid");
var currCycle = getCurrentCycle();var prevValue = null;
var prevValueFound = false;

function getPrevValue(item){
    if(prevValueFound) return;
    if(item.visitName==visitName && item.cycleNumber==currCycle){
        prevValueFound = true;        return;
    }
    if(item.eventType!='UnScheduleAbleVisit' && item.value!=null)
        prevValue = item.value;    
}    

var res = getValues('brDateForFunc');
if(res){
    brDateForFunc.forEach(getPrevValue);            
         //in case the next visit should be found the array should be reverted:
         //brDateForFunc.reverse().forEach(getPrevValue);  
       
//here should go the necessary logic to compare brDate with previous value which is now in variable prevValue
}

Example 3-107 Find the last or closest next value with target and operands on different forms

Rule variables:

aeDate- rule variable which references date on AE form.
cycleDate1 - rule variable which references date on the first cycle visit.
cycleDate2 - rule variable which references date on the second cycle visit.
cycleCheck1 - rule variable which references some condition on the first cycle visit.
cycleCheck2 - rule variable which references some condition on the second cycle visit.
vsd - visit start date with All Visits option

var lastStartedlVisit = null;
var lastVisitFound = false;
var cycleDate = null;
var cycleCheck = null;
var cycleNumber = null;

function getLastStartedlVisit(item){
    if(lastVisitFound || item.eventType=='UnScheduleAbleVisit') return;

      //condition may depend on where the point of comparison is, at some situation it can be <if(item.value==null)> or something else
    if(item.eventType=='AdverseEvent'){
        lastVisitFound = true;
        return;
    }     
if(item.value!=null) {
        lastStartedlVisit = item;
   }
}

function findItem(item, index){
    if(item.cycleNumber === cycleNumber){
        if(this.valueOf()=='cycleDate') cycleDate = item.value;
        if(this.valueOf()=='cycleCheck') cycleCheck = item.value;
    }
}

var res = getValues('vsd');
if(res){
    //the first visit before AE
    vsd.forEach(getLastStartedlVisit);
    
    //in case the next visit should be found the array should be reverted:
    //vsd.reverse().forEach(getLastStartedlVisit);
    
    cycleNumber = lastStartedlVisit.cycleNumber;
    res = getValues('cycleDate1');
    if( cycleDate1[cycleDate1.length-1].visitName == lastStartedlVisit.visitName){
       cycleDate1.forEach(findItem, 'cycleDate');
       res = getValues('cycleCheck1');
       cycleCheck1.forEach(findItem, 'cycleCheck');
   }
   else{
       res = getValues('cycleDate2');
       if( cycleDate2[cycleDate2.length-1].visitName == lastStartedlVisit.visitName){
             cycleDate2.forEach(findItem, 'cycleDate');
             res = getValues('cycleCheck2');
             cycleCheck2.forEach(findItem, 'cycleCheck');
       }
    }
}
//logMsg(JSON.stringify(aeDate))
//logMsg(JSON.stringify(cycleDate));
//logMsg(JSON.stringify(cycleCheck));
//logic to compare cycleDate cycleCheck and aeDate

Example 3-108 Compare date with next visit start date

Rule variables:

brDate - rule variable which references date.
vsd - rule variable which references visit start date with All Visits option.

var visitName = getCurrentVisitPropertyValue("visitid");
var currCycle = getCurrentCycle();
//logMsg(visitName);
//logMsg(currCycle);
//logMsg(brDate);
var nextValue = null;
var nextValueFound = false;

function getNextValue(item){
    if(nextValueFound) return;
    if(item.visitName==visitName && item.cycleNumber==currCycle){
       nextValueFound = true;
       return;
    }
    if(item.eventType!='UnScheduleAbleVisit' && item.value!=null)
          nextValue = item.value;
}

var res = getValues('vsd');
if(res){
      vsd.reverse().forEach(getNextValue);
      //logMsg(nextValue);
      //logMsg(brDate);
      //compare next vsd with cycle date: vsd
}

Parent topic: Formatting and other functions