getValues( )

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

Note:

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.

When used with a two-section form, GetCurrentRFInstance( ) can be used to restrict the rule to run only on the current two-section form instance.

Syntax

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

Parameters

'var1', 'var2', ...

Rule variable names (which define the visit, form, or item).

Return value

Returns true on success; otherwise, false.

Also, during the call to this function, rule variables are redefined with the gotten value as var1, var2, ... additionally each variable holds an array with attributes.

Tip:

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 the 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.

Limitations

• The amount of data which is returned by getValues( ) can be significant if the question exists in more than one visit. This can impact performance of the data submit.
• 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.

Example 3-102 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-103 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-104 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-105 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-106 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-107 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
}